# Agent Memory

Agent Memory gives pi agents durable knowledge that can survive beyond a single conversation and be reused in future work.

## Language

**Memory**:
A durable fact or preference the agent may retrieve and use in future turns. A **Memory** belongs to exactly one **Memory Store** and is created by explicit user instruction, user-confirmed agent proposal, or an automated agent with the required **Memory Capability**.
_Avoid_: Note, cache entry, recollection

**Memory Candidate**:
A possible **Memory** identified by the agent but not yet saved. A **Memory Candidate** becomes a **Memory** only after user confirmation or by an agent with the required **Memory Capability**.
_Avoid_: Auto-memory, inferred memory

**Memory Store**:
A named storage location containing **Memories**, **Topic Files**, and a **Retrieval Map**. A Memory Store is the boundary for retrieval, storage, and permissions.
_Avoid_: Scope, namespace, bucket

**Memory Capability**:
A future-facing permission granted to an agent for memory mutation operations. Memory Capability is not active in v1, where Structured Memory Writes happen only inside explicit user-invoked commands.
_Avoid_: Profile, role, trust level, read permission

**Forget**:
To remove a **Memory** from the current Markdown files in a **Memory Store** so it is no longer available for active retrieval. Forgetting does not rewrite git history.
_Avoid_: Archive, retire, hide

**Project Store**:
The built-in **Memory Store** for memories that apply to one repository or working directory. The Project Store lives at the fixed project path `.pi/memory/`.
_Avoid_: Project Scope, repo memory, local memory

**Global Store**:
A deferred **Memory Store** concept for memories that apply across repositories for the user. Global Store is not part of v1.
_Avoid_: Global Scope, user memory, universal memory

**Retrieval Map**:
A lightweight Markdown index that helps agents retrieve relevant **Memories** using text search. A Retrieval Map uses topic summaries, concepts, aliases, relationships, and paths; it does not use vectors or duplicate full memory content.
_Avoid_: Vector index, embedding store, full memory mirror

**Topic File**:
A Markdown file containing multiple related **Memories** for a concept area. Topic Files are the canonical storage unit for memories and are created lazily on first write.
_Avoid_: Per-memory file, memory blob

**Memory Block**:
A structured Markdown section inside a **Topic File** that represents one **Memory**. A Memory Block uses the stable memory id as its heading, followed by plain metadata lines, a canonical content hash, and body text; it does not have a separate title.
_Avoid_: YAML block, database row, titled note

**Canonical Content Hash**:
A SHA-256 version identifier for a **Memory Block** computed from canonicalized semantic fields, excluding `Updated` and excluding the hash field itself. Canonical Content Hashes let Structured Memory Writes detect stale update or forget operations without treating generated metadata churn as a conflict.
_Avoid_: Checksum, etag, raw markdown hash

**Memory Consultation**:
A built-in tool access to a **Memory Store** file that indicates the agent has read or searched memory. In v1, Memory Consultation is shown in the UI only and is not persisted as a custom session entry.
_Avoid_: Memory read tool, memory search tool

**Memory Snapshot**:
The exact set of **Memory Blocks** and version identifiers an agent has consulted before acting. A Memory Snapshot is the basis for detecting stale memory updates when other agents may have changed the same **Memory Store** concurrently.
_Avoid_: Loaded memory, memory in brain, memory context

**Structured Memory Write**:
A change to a **Memory Store** performed through a memory-specific tool that preserves **Memory Block** format and keeps the **Retrieval Map** current. Built-in file write tools are not valid Structured Memory Writes.
_Avoid_: Direct edit, manual memory patch

**Memory Tool Surface**:
The set of memory-specific tools available to agents. In v1, the normal Memory Tool Surface exposes `memory_stores` only; `/memory extract` temporarily exposes non-mutating `memory_candidate`. Retrieval uses built-in file tools against the Retrieval Map and Topic Files, and Structured Memory Writes are performed internally by the extension after user approval.
_Avoid_: Memory search API, memory read API, public memory write tool

**Memory Recall Prompt**:
A prompt template that asks an existing scout-style agent to retrieve relevant Memories from the Project Store. Memory Recall Prompt reuses general retrieval agents instead of defining a dedicated memory retrieval agent.
_Avoid_: Dedicated memory retriever agent, memory search tool

**Memory Extraction**:
An explicit user-invoked workflow that inspects the current session branch, proposes Memory Candidates, and writes approved candidates to the Project Store. Successful Memory Extraction writes a non-context checkpoint entry with the created memory ids.
_Avoid_: Background memory harvesting, silent memory write

**Memory Authority Source**:
The mechanism that grants Memory Capabilities to an agent invocation. In v1, installing the project-local extension does not grant mutation authority by default; mutation authority is tied to explicit automation behavior that is still being designed.
_Avoid_: Prompt-only permission, model trust profile, model trust config

**Deduplication**:
Surfacing a **Memory Candidate** that restates an existing **Memory** so it is not written twice. Authoritative judgement of "same fact" can require repository context, so v1 Deduplication is a best-effort, store-only flag decided by the human reviewer; autonomous, repo-grounded Deduplication is a responsibility of the future Memory Health agent.
_Avoid_: Merge, collapse, dedupe-on-write

**Memory Health**:
The degree to which a **Memory Store**'s **Memories** remain accurate and relevant relative to the current state of the repository. Assessing Memory Health requires investigating the codebase, not just reading the store, which is why it is the work of an autonomous agent rather than a mechanical check.
_Avoid_: Freshness, correctness, quality score

**Memory Staleness**:
The condition of a **Memory** whose body no longer reflects the current state of the repository. Memory Staleness shares its root meaning with Retrieval Map staleness (the **Retrieval Map** behind its **Topic Files**) and Hash staleness (a **Memory Block**'s `Hash:` behind its content) — in every case a recorded thing has fallen out of sync with its source of truth — but only Memory Staleness requires repository investigation to detect; the other two are mechanically detectable.
_Avoid_: Drift, rot, outdated

## Example dialogue

Dev: "Should the agent remember that this repo uses ADRs for hard-to-reverse decisions?"
Domain expert: "Yes, that belongs in the Project Store because it applies to this repository."

Dev: "Should the agent remember that I prefer concise answers?"
Domain expert: "Yes, that belongs in the Global Store because it applies across repositories."