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 convention
- Preference: an explicit or confirmed way you want work handled
- Decision: an architectural or product choice and the reason it was made
- Issue: 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
- Whether you asked to save it or Embedder inferred it
- 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 shows you the proposed entry before writing it. Saving always requires your confirmation.
To update an entry, ask Embedder to find the existing memory and replace it. The original creation time is preserved.
The store rejects common sources of clutter:
- A new entry cannot duplicate a similar preview of the same kind.
- 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
Ask a question in ordinary language:
Embedder searches previews, keywords, paths, and full content. You can also ask it to list entries for one area tag, then open the matching entries.
Pinned and recently updated entries are preferred when several results are equally relevant.
Pin an entry
Pinned entries are 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 shows a destructive confirmation, then deletes the entry. Memory deletion is available in Act mode. Read and save operations are also available in Plan mode.
Limits
- 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 at a time
- Expansion: up to 10 entries at a time
- Store: 50 entries, including up to 5 pinned entries
Embedder normalizes tags to lowercase and removes duplicate tags and keywords.
Storage and recovery
For a writable project, memory is stored in:
If the JSON file is corrupt, Embedder moves it aside 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. Ask Embedder to
save, update, pin, or forget so validation, duplicate checks, and pin limits
remain active.
