Remember
Store a fact directly:remember tool it calls on your behalf.
Every stored perception carries a kind tag. xynthis remember stores as a user message; the agent’s tool defaults to note and accepts tags like decision, insight, preference, and file_edit. The kind matters for length limits: user messages are never truncated, notes are capped at 800 characters, everything else at 500. Longer content is treated as a dump, not a fact. Split it or use codebase memory for documents.
Recall
Two commands read memory back.xynthis ask is the day-to-day one:
ask runs the brain’s layered retriever, drops noise, and prints the top clean matches with scores: no LLM call, zero tokens, milliseconds. If the top hit scores at least 0.6, or at least 0.5 with substantial content, the answer is shown as confident. Below that you get the hits with a low-confidence warning and a suggestion to run xynthis chat for an LLM-reasoned answer instead. Tune with --top-k (default 3) and --threshold (default 0.5).
xynthis recall "<query>" returns the raw layered response as JSON: binary (long-term facts), kg (knowledge-graph triples), and working_memory (current-session context). Each binary hit carries:
| Field | Meaning |
|---|---|
id | The record id, used by confirm, why, and forget |
content | The stored text, verbatim |
final_score | Similarity blended with learned reranking, recency, and access frequency |
trust | A 0-1 truthfulness estimate for the fact |
grounded | Whether the fact still matches its source (false means it has drifted) |
witness | Present once you have cryptographically confirmed the fact |
◆ for trust ≥ 0.80, ◇ for 0.50-0.79, · below, plus grounded or drifted, and ✓ signed for confirmed facts.
Confirm and audit
When a recalled fact matters, you can vouch for it:~/.xynthis/bmc/identity.ed25519 and appends one row to the append-only log at ~/.xynthis/bmc/witness.log. Both files live in the brain’s data directory, ~/.xynthis/bmc/. Future recalls of that fact show ✓ signed. Because the signature hashes the live stored text, a later edit to the fact invalidates it.
why prints the audit trail: the signed payload, the signature, and an inclusion proof. The output verifies offline against your public key alone.
Forget
Forgetting is a soft delete: the record is marked stale and stops appearing in recall from the next query on. Take theid from a recall response and post it to the daemon:
POST /api/kg/forget, keyed on subject, predicate, and object.
What never gets stored
Every incoming perception (from chat,remember, the app, or the MCP bridge) passes a write-time filter in the brain before it touches storage. The filter has three outcomes:
- Stored: a durable fact. This is the only lane that reaches long-term memory.
- Session-only: questions you ask (“what do you remember about X?”), task and command fragments, and the agent’s own narration and greetings. These stay in working memory so the current session can use them, but they never become durable facts. Without this, your questions would come back as top recall hits and bury real answers.
- Rejected: never stored anywhere. This covers content matching the privacy blocklist, tool-call echoes, raw shell output, the agent’s injected prompt scaffolds, and oversized dumps.