> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xynthis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Working with memory

> Store, recall, confirm, and forget facts, and understand what the brain refuses to keep.

## Remember

Store a fact directly:

```bash theme={null}
xynthis remember "the production database is postgres 16 on the hetzner box"
```

This sends the text to the brain as a perception, the same path a chat message takes. You can also just tell the assistant to remember something mid-conversation; the agent has a `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](/guides/codebase-memory) for documents.

## Recall

Two commands read memory back. `xynthis ask` is the day-to-day one:

```bash theme={null}
xynthis ask "what did I decide about the deploy window?"
```

`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               |

Surfaces that render recall briefly (the app, the MCP bridge) compress trust into a chip in front of each hit: `◆` 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:

```bash theme={null}
xynthis confirm 8412
```

This signs the fact (its id, a hash of its content, the time, and your identity) with the local Ed25519 key at `~/.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.

```bash theme={null}
xynthis why 8412
```

`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 the `id` from a recall response and post it to the daemon:

```bash theme={null}
curl -X POST localhost:3939/api/perceptions/forget \
  -H 'content-type: application/json' -d '{"id": 8412}'
```

The app exposes the same action on individual memories. Knowledge-graph triples have their own endpoint, `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.

The privacy blocklist is a hardcoded list of substrings, matched case-insensitively, for things you have asked never to be stored. Because the filter runs at write time inside the brain, filtered content cannot surface in any later recall: it was never written.

## Free tier vs Pro

On the free tier, long-term recall returns only facts created in the last 7 days. Pro and Team recall unlimited history. The cap is applied at read time (everything is still stored), so upgrading immediately restores access to older memories. The window applies to the long-term fact layer; current-session working memory is unaffected.