Memory and recall
Durable facts, relevance selection, linked entries, and concurrent updates.
Memories are the agent's persistent notebook. They belong to one profile and can be recalled across that profile's conversations. They are not the same as a chat transcript, a compaction summary, or a skill.
What belongs in memory
Good entries change how the agent should work later: a stated preference, a project convention, a decision and its reason, or a correction from the owner. Avoid temporary plans, inferred personal facts, raw chat dumps, and secrets.
A useful entry might use the key harbor-status-reports and say:
Harbor Studio's weekly status report starts with the outcome, then blockers, then the next action. Since October 2026, the owner wants it under 200 words, with links to the original tasks.
A key names the subject, rather than the date the entry happened to be saved. When a fact changes, updating one entry avoids two conflicting memories being recalled later.
How recall works
- Jian compares words in the current request with memory keys and contents to form a relevance shortlist.
- Where configured, Decisions can judge the shortlist for semantic usefulness. Irrelevant judged entries are excluded, and useful ones can be ranked higher.
- Entries are added until the profile's memory token budget is reached.
- Directly linked entries may follow their matched neighbors, if space remains.
This is bounded, selective recall, not a promise that every saved memory is inserted into every request. A newly updated entry helps break ties. The agent can also call read_memories to search explicitly when the initial context is insufficient.
Links between memories
Link a project to its conventions, or a decision to the constraint behind it. Recalling one can bring the other even if the request did not use the second entry's words.
Recall follows one hop, not an unlimited graph traversal. A memory can have up to 12 links. Linking everything wastes the same context budget meant to preserve relevance.
Writing and editing
The agent uses remember with a key, content, and expectedVersion. The owner can inspect, edit, link, and delete entries under Customize → Memories.
| Field | Contract |
|---|---|
key | Lowercase letters, digits, -, _; up to 100 characters |
content | Nonempty text; up to 4,000 characters |
expectedVersion: 0 | Create a new key |
| Existing version | Update only if that version still matches |
Version checks prevent two conversations from silently overwriting each other's edits. After a conflict, reread the current entry and reconcile the content. Do not repeatedly resubmit an old version.
A successful tool response is the evidence that the memory was saved. An agent saying “I'll remember” without a successful write does not persist anything.
Deleting and correcting
forget_memory removes the entry and its links. Removing a memory does not erase statements that already exist in conversation history. If the same fact is still in old messages or summaries, the agent may encounter it there; make a changed preference explicit in the current conversation too.
A fact about another channel contact should not become a persistent profile memory merely because that person mentioned it. The built-in guidance reserves that kind of retention for the owner's instruction.
Memory, history, skills, and learning
| Mechanism | Purpose |
|---|---|
| History | What happened in a particular conversation; searchable when detail is needed |
| Compaction summary | A shorter representation of older conversation context |
| Memory | A durable fact or preference reused across this agent's conversations |
| Skill | A reusable procedure loaded for a kind of work |
| Learning review | A process that decides whether a completed experience deserves a memory or skill |
See conversation context, skills, and automatic learning.