Skip to main content
Memory lets an agent retain useful facts and preferences beyond the recent conversation window. Each agent owns its own memory. A turn receives only a bounded selection that is relevant and permitted for its audience. For example, “I prefer concise updates” can become a preference about the person who said it. A fact learned in their direct message remains private; relevance to a public discussion does not grant permission to disclose it there.

​
Using memory

An agent can recall a fact before correcting or forgetting it. Committed memory operations are supplied to the response generation step; a failed or unchanged write must not be described as a successful mutation. Forgetting does not erase previously delivered messages or the operation history. Operators can inspect and edit memories on the agent’s Memory page. Dreaming can also learn and maintain memories in the background under its configured limits and the same disclosure rules.

​
Subject, source, and permission

These are separate properties:
  • Subject: whom the fact concerns; it influences relevance.
  • Source: who supplied it and which evidence supports it.
  • Permission: which destination audiences may receive it.
Source attribution comes from authenticated records, not a model-provided author claim. Names are rendered from actor records rather than embedded as permanent identity labels in memory text. Identity links can change read-time associations without rewriting the original evidence. Memory privacy defines source audiences, inherited restrictions, explicit sharing, and final delivery checks.

​
Selection for a turn

Automatic context and recall share one retrieval service. SQL first restricts candidates to the current agent, live revision, and permitted audience. Ranking cannot restore an ineligible row. The default backend uses PostgreSQL full-text search with subject, conversation, and recency signals. Optional pgvector or Qdrant backends add semantic matches. Lexical and semantic ranks are combined, then current canonical rows and permissions are checked again. Nonempty searches normally require lexical or semantic relevance. Empty searches use subject, conversation, and recency ordering. Automatic context additionally considers a bounded set of eligible preferences and communication-style memories for current participants, even when their text does not match the topic. Relevant task evidence ranks ahead of these supplemental actor profiles. The default memory allowance is 4,096 estimated tokens, configurable from 256 to 32,768. Whole entries are selected; oversized entries are skipped instead of being cut into potentially different claims. Prompt admission then fits memory alongside history, images, tools, and the current message. PostgreSQL remains authoritative. Embeddings are disposable projections of immutable revisions. A stale vector cannot revive a forgotten or amended memory, and a provider result cannot bypass source permissions. Each candidate source is bounded. Semantic retrieval has a three-second deadline and a 10,000-revision eligible-set cap. Missing, rebuilding, unavailable, or oversized indexes fall back to authorized lexical retrieval. Learned reranking, explicit salience scores, and confidence-based ranking are not implemented. Memory providers covers configuration, confidential processing, index rebuilds, and provider requirements.

​
Diagnosing retrieval

memory_retrieval_events records selected revisions, score components, estimated cost, destination audience, and degradation categories. Query text is not stored there: a keyed digest supports correlation without a guessable plain hash. Prompt snapshots and tool observations still contain actual context within the administrator trust boundary. eligibility_withheld_unknown means matching memories lack sufficient audience evidence. It calls for source review, not a weaker search filter. Permissions are checked again before the final answer is delivered. Implementation: internal/memory/retrieval.go (repository), db/queries/memory_retrieval.sql (repository), and internal/turn/memory_verbs.go (repository).