Project memory keeps durable facts available across conversations. Use it for knowledge that should change how future work is done in the same project, such as a build constraint, an architectural decision, or a confirmed hardware issue.
Conversation history and project memory are separate. Clearing a conversation does not remove saved project memory.
What belongs in memory
Each entry has one of four kinds:
pattern: a recurring implementation or project conventionpreference: an explicit or confirmed way you want work handleddecision: an architectural or product choice and the reason it was madeissue: a durable, known problem or constraint
An entry also records:
- One to five broad area tags, such as
build, dma, or auth
- Up to ten specific search keywords
- A one-line preview and detailed content
- Optional related file paths
- A source of
explicit or inferred
- An optional pinned state
- Creation and update timestamps
Use memory for stable project knowledge. Keep temporary debugging observations, guesses, and task progress in the current conversation.
Save or update an entry
Ask Embedder to remember a confirmed fact:
Embedder prepares a save_memory operation and shows you the proposed entry before writing it. Saving always requires your confirmation.
To update an entry, Embedder searches for the existing memory, expands it, and saves the replacement using the same entry ID. This preserves its creation time and updates its modification time.
The store rejects common sources of clutter:
- A new entry cannot duplicate a similar preview of the same kind. Update the returned existing ID instead.
- A new broad tag cannot be almost identical to an existing tag. Reuse the suggested tag.
- The project can hold at most 50 entries.
- At most five entries can be pinned.
Paths inside the project are stored relative to the project root. External absolute paths stay absolute.
Recall memory
Embedder uses three read operations:
memory_search searches previews, keywords, paths, and full content. Use it for broad questions.memory_list_area returns entries with one exact broad tag. Use it when you already know the area from the startup index.memory_expand loads the full content for up to ten entry IDs returned by search or area listing.
For example:
Embedder should search memory before reading the codebase when the startup index shows a related area. Search results contain previews and IDs, so it expands only the entries needed for the answer.
Search scores phrase and word matches across previews, keywords, paths, and content. Preview matches receive the highest weights. Pinned and recently updated entries break equal-score ties.
Pin an entry
Pinned entries are for constraints the agent must see at the start of every conversation. A pin includes the entry’s full content in the startup context.
Unpinned entries stay searchable. At startup, Embedder includes only the tag index and entry counts for them, which keeps the context small.
Use pins sparingly:
Updating an entry can pin or unpin it. The five-pin limit prevents project memory from becoming another large instruction file.
Forget an entry
Ask Embedder to remove knowledge that is wrong, obsolete, or irrelevant:
Embedder resolves the entry ID, shows a destructive confirmation, and then runs forget_memory. Memory deletion is available in Act mode. Read and save operations are also available in Plan mode.
Limits
The entry format enforces these bounds:
- Tags: 1 to 5 per entry, with a 20-character limit per normalized tag
- Keywords: up to 10 per entry
- Preview: up to 150 characters
- Content: up to 2,000 characters
- Search and area listing: up to 20 previews per call
- Expansion: up to 10 IDs per call
- Store: 50 entries, including up to 5 pinned entries
Embedder normalizes tags to lowercase, removes duplicate tags and keywords, and writes the store under a cross-process lock.
Storage and recovery
For a writable project, memory is stored in:
Writes use a temporary file and an atomic rename. If the JSON file is corrupt, Embedder moves it to a timestamped .memory.json.corrupt.* file and starts with an empty store. The quarantined file remains available for manual recovery.
Do not edit memory.json while Embedder is saving an entry. Use the memory
operations so validation, locking, duplicate checks, and pin limits remain
active.
