Kb Chat

1. Check for an existing active session:

python3 -m llm_notes.chat list --kb-root <kb-root> --status active --limit 1

2. If there is no suitable active session, create one:

python3 -m llm_notes.chat start \
  --kb-root <kb-root> \
  --title "<short session title>" \
  --focus "<what this multi-turn discussion is trying to learn>"

3. Append the current user message to the session transcript before researching:

python3 -m llm_notes.chat append \
  --kb-root <kb-root> \
  --session <session rel_path or session_id> \
  --speaker user \
  --content-stdin <<'EOF'
<raw user message>
EOF

Step 3: Research The KB

Use the same navigation discipline as /kb-qa:

1. Read wiki/_index.md
2. Read relevant category _index.md files
3. Use /kb-search only when the question is broad, ambiguous, or cross-cutting
4. Read the strongest 3-10 candidate articles
5. Extend the local knowledge network through [[wikilinks]], sibling pages, contrasts, and prerequisites
6. Read KB-root source files directly when wiki coverage is insufficient
7. Track gaps, contradictions, and follow-up threads that arise during the session

Step 4: Answer In-Session

Reply conversationally, but keep KB discipline:

• Ground claims in the articles you actually read
• Use inline [[wikilinks]] citations when referring to wiki pages
• Surface contradictions, gaps, and next questions
• For substantive turns, prefer the same four-section structure as /kb-qa:
  • ## Main Conclusion
  • ## Knowledge Network Extension
  • ## Deep-Dive Threads
  • ## Further Questions

Step 5: Append The Assistant Turn

After you draft the reply, append it to the same session transcript:

python3 -m llm_notes.chat append \
  --kb-root <kb-root> \
  --session <session rel_path or session_id> \
  --speaker assistant \
  --source-consulted wiki/category/article.md \
  --source-consulted wiki/category/other-article.md \
  --content-stdin <<'EOF'
<assistant reply shown to the user>
EOF

Step 6: Promote Stable Synthesis

When the session reaches a durable conclusion, comparison, taxonomy, or reusable concept link:

1. Save and auto-file a synthesized answer note:

python3 -m llm_notes.answers finalize \
  --kb-root <kb-root> \
  --question "<stable question distilled from the session>" \
  --source-consulted wiki/category/article.md \
  --source-consulted wiki/category/other-article.md \
  --no-auto-file \
  --body-stdin <<'EOF'
# <Distilled Question>

## Main Conclusion

...

## Knowledge Network Extension

...

## Deep-Dive Threads

...

## Further Questions

...

## Sources Consulted

...

## Gaps Identified

...
EOF

2. Register the generated answer note and any filed wiki targets back onto the session:

python3 -m llm_notes.chat link-answer \
  --kb-root <kb-root> \
  --session <session rel_path or session_id> \
  --answer outputs/answers/YYYY-MM-DD-slug.md

link-answer now inspects the answer note itself:

• if the answer was already filed, it registers the filed wikilinks back onto the session automatically
• if the answer is still pending but the filing model recommends new or enrich, it writes that recommendation and exact command into the session's Promotion Queue

3. In interactive assistant workflows, use the session's promotion queue to ask before filing:

• Saved the distilled answer and added a promotion recommendation to the session. Do you want me to file it into the wiki now?

Promote when the insight is reusable. Do not promote transient chatter or purely operational turns. Only skip the confirmation step when the user explicitly asked to file the conclusion back into the wiki as part of this turn.

Step 7: Close The Session

When the user explicitly finishes the topic, close the session:

python3 -m llm_notes.chat close \
  --kb-root <kb-root> \
  --session <session rel_path or session_id> \
  --status closed

The goal is:

• outputs/sessions/ keeps the auditable transcript
• outputs/answers/ keeps distilled synthesis notes
• wiki/ receives only stable, reusable knowledge