Memory Model

Memory

A memory is a durable record the user expects the agent to use in future sessions. The Memory Governance contract defines target metadata for keeping records inspectable, reviewable, and contestable as they age.

{
  "id": "mem_01HZY...",
  "revision": 1,
  "scope": "user:default",
  "kind": "preference",
  "content": "The user prefers concise implementation plans before large edits.",
  "tags": ["codex", "workflow"],
  "source": "codex:mcp",
  "confidence": 1.0,
  "confidence_state": "user_confirmed",
  "provenance": null,
  "review_after": null,
  "expires_at": null,
  "created_at": "2026-06-11T00:00:00Z",
  "updated_at": "2026-06-11T00:00:00Z",
  "last_used_at": null,
  "archived_at": null
}

Kinds

kind is the current public compatibility field. Do not add new allowed values without updating tool schemas, validation, import/export behavior, and compatibility documentation. Future durability classes such as repo convention, task state, and lesson learned are specified in Memory Governance.

• preference: stable user preference.
• project_decision: durable project decision.
• fact: stable fact about the user, project, or environment.
• instruction: recurring instruction the agent should follow.
• note: general durable note.

Scopes

• user:default: global user memory.
• project:<path-hash>: local project memory.
• agent:<name>: memory specific to one agent.
• team:<name>: future team-level memory.

Valid scopes use the shape <kind>:<id>, where kind is user, project, agent, or team. Scope IDs may contain letters, numbers, ., _, ~, :, /, and -.

Tags

Tags are lightweight labels used for filtering and retrieval.

Tags must be lowercase labels that start with a letter or number. They may contain lowercase letters, numbers, ., _, and -, up to 64 characters.

Recommended initial tags:

• codex
• project
• preference
• architecture
• security
• workflow

The autoload tag has defined host-integration semantics. Active memories with this tag may be included in a bounded, read-only session bootstrap before the first user prompt. Use it only for context that should apply broadly whenever its scope is active, such as a durable project convention or global response preference. Topic-specific memories should use descriptive tags such as cloudflare, docker, or release and rely on contextual recall instead.

Tags are retrieval metadata, not instructions or authorization. Hosts may suggest topical tags for a capture draft, but inferred tags remain part of the user-confirmed draft and must never trigger a silent write.

Confidence

Confidence is a number from 0.0 to 1.0.

Nuzo defaults explicit user-approved memories to 1.0.

Inferred or suggested memories should not be saved without confirmation. If saved, they can use lower confidence and include source metadata.

Confidence is not an authorization or instruction-priority signal. Recalled content remains stored data even when confidence is 1.0. Human-readable confidence states such as observed, inferred, user_confirmed, needs_review, and deprecated complement the numeric score and are defined by Memory Governance.

Review Lifecycle Metadata

review_after and expires_at are optional ISO timestamps. They are governance metadata, not automatic deletion rules.

• review_after: after this timestamp, Nuzo should show the memory as due for review.
• expires_at: after this timestamp, Nuzo should show the memory as expired or requiring confirmation before strong use.

Active memories whose review_after or expires_at is due can be listed with the CLI --needs-review filter and the MCP needs_review list filter. Nuzo does not automatically archive, delete, or rewrite a memory when either timestamp passes.

Explicit Memory Relations

Memory relations are durable, user-visible links between two memory records. They are manual/auditable metadata, not automatic recall authority and not a silent write path.

Supported relation types:

• supersedes: the source memory replaces or narrows the target memory.
• conflicts_with: the source memory contradicts the target memory and both should be reviewed before strong use.
• duplicate_of: the source memory is a duplicate of the target memory.
• related_to: the source memory is topically related to the target memory.

Relations are directional in storage:

{
  "id": "rel_01HZY...",
  "source_memory_id": "mem_current",
  "target_memory_id": "mem_previous",
  "relation": "supersedes",
  "reason": "Newer deploy decision replaces the older note.",
  "created_at": "2026-06-11T00:00:00Z"
}

List and recall surfaces may show compact relation annotations, but recalled memory content remains evidence to inspect rather than an instruction to obey. Clients should surface conflicts, duplicates, and supersession markers whenever they use related memories to guide work.

Inspection And Challenge

Nuzo exposes a progressive inspection flow:

1. compact memory.list or memory.recall results;
2. memory.show for one record with full metadata, relations, and audit events;
3. memory.challenge for an explicit review decision.

Challenge outcomes are:

• valid: revalidated by the user;
• needs_review: should be checked before strong use;
• stale: likely outdated;
• incorrect: known wrong;
• superseded: replaced by another memory.

Challenge does not delete content and does not create inferred memory. It only updates confidence/review metadata, appends memory.challenged, and, for superseded, creates an explicit supersedes relation.

Source, Provenance, And Recall Trust

source records attribution supplied by the writer, such as codex:mcp or an import path. It helps users audit where a memory came from, but it is not an authenticated identity and must not grant additional authority.

Audit event actor records the Nuzo surface that performed an operation, such as nuzo:cli, nuzo:mcp, core, or a test/import actor. source belongs to the memory record; actor belongs to an event. Together they provide provenance for explicit writes, confirmed capture, imports, CLI actions, MCP actions, and host integrations.

Creation actors are assigned at the trusted operation boundary rather than copied from source: direct MCP writes and MCP-confirmed capture use nuzo:mcp, direct CLI remember uses nuzo:cli, and library calls that omit an actor use core. The administrator-oriented CLI may still accept an explicit actor for confirmed or maintenance operations. An arbitrary source must never be treated as proof that a particular Nuzo surface performed the write.

Audit payloads are metadata-only. They may include scope, tags, kind, count, reason, changed fields, a query hash, or score, but they must not retain memory content or full recall queries. This keeps hard-deleted memory content deleted and avoids copying sensitive prompt text into the audit log while preserving enough history to verify that an operation occurred.

Opt-in memory.recalled events use a lowercase, 64-character SHA-256 queryHash plus queryHashAlgorithm: "sha256" for correlation. The hash is not encryption and must not be treated as secret or as proof of the original query. Existing events created by earlier Nuzo versions may still contain a legacy query field; migrations leave those historical payloads unchanged.

During recall, every memory's content is treated as untrusted stored data. This includes explicit user writes, confirmed capture, imported memories, and records shared by multiple hosts. The instruction kind describes intended future usefulness; it does not place content in the host's system, developer, plugin, or current-user instruction hierarchy.

Automatic lifecycle context preserves bounded content with its ID, revision, scope, kind, tags, and source inside the rendering contract defined by Memory Trust Boundary. Structured provenance preserves this trust boundary and remains bounded attribution metadata. It is optional and does not replace source.

{
  "source": "codex:capture-confirmed",
  "provenance": {
    "kind": "conversation",
    "host": "codex",
    "surface": "mcp",
    "path": "AGENTS.md",
    "line": 42,
    "action": "capture_confirmed",
    "reason": "User confirmed a recurring repository convention."
  }
}

Provenance fields are metadata for audit and review. Paths must be relative, line numbers must be positive integers, and reason text is bounded and secret-scanned.

Lifecycle

suggested -> created -> updated -> archived -> deleted

Deletion should support two modes:

• archive: hide from recall but retain audit metadata;
• hard delete: remove content from the store.

Revisions

Each memory has a monotonically increasing revision.

The initial revision is 1. Updates, archive operations, hard deletes, and explicit recall-usage metadata writes compare against the revision that was read before the write transaction. If another process commits a newer revision first, the operation must fail with MEMORY_REVISION_CONFLICT instead of silently overwriting the newer state.

Clients that edit or delete a memory after showing it to a user should pass the last seen revision as expected_revision. If the current revision differs, the client should re-read the memory, show the newer state, and ask the user to confirm the operation again.

Import deduplication uses the normalized memory identity of scope, kind, content, and tags. For the SQLite MVP, import planning runs inside the write transaction so equivalent concurrent imports serialize deterministically. A database-level normalized uniqueness index remains optional future hardening if Nuzo adds storage adapters without equivalent transactional behavior.

Retrieval Result

Recall responses should include enough context for the agent to use memory responsibly:

{
  "memory": {
    "id": "mem_01HZY...",
    "revision": 1,
    "kind": "preference",
    "content": "The user prefers concise implementation plans before large edits.",
    "tags": ["codex", "workflow"],
    "confidence_state": "user_confirmed",
    "review_after": null,
    "expires_at": null
  },
  "score": 0.82,
  "scope": "user:default",
  "reason": "Matched query terms: concise, plans, edits"
}