Remember facts across sessions
Keep durable preferences, cited project facts, and reusable procedures available to future sessions.
Memory lets you carry useful knowledge from one session into another without repeating it. Storage is local, and the REPL, Telegram, afk chat, and daemon sessions share it when they use the same state directory. Recalled content still enters the model's context, so local storage does not mean that content stays off the model provider's servers.
Save and recall something useful
Ask for a durable fact
Remember that this project uses pnpm exclusively. Verify the packageManager field and save the fact with a file citation.The agent uses memory_update with target: "fact". A preference, project convention, decision, or debugging lesson belongs in the searchable archive, not automatically in every future prompt.
Recall it in a later session
Search memory for this project's package manager convention, then check whether the current package.json still agrees.memory_search retrieves facts and procedures. A remembered citation is a lead to check, not proof that a file has stayed unchanged.
Replace outdated knowledge
Ask the agent to supersede the old fact and supply fresh evidence. action: "supersede" preserves the original in history and removes it from normal active-fact search results. Use action: "remove" only when you intend to delete a fact.
Choose the right storage tier
| Store | Location under ~/.afk/state/memory/ | Use it for |
|---|---|---|
| Hot memory | HOT.md | Identity and a few durable preferences needed in every session |
| Fact archive | memory.db | Searchable conventions, decisions, preferences, and learnings |
| Procedures | procedures/<name>.md | Reusable workflows with steps and verification criteria |
The archive uses SQLite with WAL mode and FTS5 search. There is no hot-memory-style character cap on individual archive storage. Facts are not automatically scoped to a repository, so include enough project context to distinguish similarly named systems.
Hot memory limits
Hot memory is loaded at session construction and included in the system prompt. It is not reread from disk before every turn, and a write affects future sessions rather than rewriting the current prompt.
Writes through memory_update enforce a 5,250 character cap, approximately 1,500 tokens. At 80% usage the tool returns a warning. Oversized writes keep the beginning, truncate the tail, and add a visible truncation marker. The first 600 characters are protected from the complete-line truncation rule.
Keep the most durable information first. Move project details into facts before the cap becomes a problem. Writes are atomic, and HOT.md.bak retains the previous version. These write-time protections do not make an oversized manually edited file safe to inject.
Hot memory is ambient context for future sessions. Avoid credentials, large task logs, and instructions copied from untrusted documents. Prefer project instructions in AFK.md for repository-specific policy.
Fact categories and tools
| Category | Example |
|---|---|
preference | Your preferred explanation style |
convention | A repository's package manager or architectural rule |
decision | A design choice and its rationale |
learning | A debugging insight or agent reflection |
The agent can save a cited fact with this tool input:
{
"target": "fact",
"action": "set",
"category": "convention",
"content": "The dashboard project uses pnpm.",
"evidence": "dashboard/package.json:8"
}The citation above illustrates the shape; the agent must use a location it actually checked. To supersede a fact, supply its numeric ID as supersedes, the replacement content, and fresh evidence. To remove it, supply id and action: "remove". Hot memory supports only action: "set", which replaces its contents.
Search syntax
memory_search takes query, optional category, optional ISO since, and limit (default 10). Fact queries support FTS5:
"exact phrase"
TypeScript AND strict
deploy OR release
postgres NOT sqlite
pnpm*Superseded facts are excluded from ordinary recall. Procedure searches use case-insensitive substring matching of query terms, not FTS5 operators. A category filter restricts results to facts and excludes procedures.
Evidence gate and stale citations
The evidence gate is on by default. Set AFK_MEMORY_EVIDENCE_GATE=0 to disable it; 1 explicitly enables it.
| Situation | Behavior with the gate enabled |
|---|---|
convention without evidence | Saved with a warning, recalled as [unverified] |
convention with evidence | Recalled with a verified provenance verdict |
learning | Recalled with [auto-reflected] |
preference, decision, or procedure | Evidence verdict is not-applicable |
The gate does not block uncited writes and does not check whether a cited file, commit, or trace actually proves the claim. verified means a nonempty citation was supplied, not that AFK independently validated its truth.
When you supersede a cited convention without supplying evidence, the old citation carries forward. The tool warns that the changed claim is still marked verified against the old evidence. Supply a current citation, or pass an empty evidence string to clear it and make the replacement unverified.
Reusable procedures
Ask the agent to save a successful workflow with procedure_write:
Save a procedure named verify-dashboard-release with the commands we used, prerequisites, expected results, and recovery steps. Exclude credentials and this run's temporary paths.The tool takes name and full Markdown content. It writes or overwrites procedures/<name>.md and adds origin metadata such as creation time and source session. Names must be 1 to 100 characters, start with an alphanumeric character, and contain only alphanumeric characters, hyphens, or underscores. Kebab case is a useful convention.
Procedures become searchable through memory_search; they are not automatically executed or injected into every prompt.
Subagents and session lifecycle
Subagents can write facts with memory_update when their tool access permits memory writes. They cannot write target: "hot": a structural guard rejects that operation even if no hook registry is installed. An explicitly read-only-memory session has only memory_search; tool restrictions can also withhold writes.
The ordinary child tool allowlist excludes procedure_write. Have the coordinator review and save a proposed procedure instead of having parallel workers overwrite a shared workflow. Session-history hooks skip child sessions rather than producing duplicate top-level history records.
Use workspace_publish and workspace_query for findings that siblings need during the current task. Persist only useful, grounded knowledge to memory. See subagent coordination for workspace behavior.
Storage and sharing
The default directory contains HOT.md, its backup, memory.db, procedure files, and a recovery log. Set AFK_STATE_DIR to relocate the state tree; memory then lives under that directory's memory/ child. All surfaces pointing at that tree see the same archive. Existing running sessions do not automatically refresh their hot-memory snapshot.
Session lifecycle hooks record session history independently of whether the agent saved any facts. Memory tools remain the explicit path for adding and correcting reusable knowledge.