Memory ingestion and reinforcement
Memory ingestion adds already-distilled knowledge to the retained memory stream without another model run. Direct saves, Claude Code memory imports, and the memory-item API provide different write surfaces; duplicate handling keeps repeated knowledge from creating noise, while reinforcement signals help useful older memories return to context.
Ingestion interfaces
The system offers separate entry points for unstructured observations, imported Claude Code notes, and structured memory items. The observation paths share the normal project scope and duplicate rules, while the memory-item API is a direct project-scoped storage surface.
Manual memory saves
POST /api/memory/save accepts one non-empty text value and turns it into a manual observation for a project. The caller can add a title and metadata. Project selection follows the request, metadata, and worker-default sources in that order. The response confirms local acceptance before later cloud and search work completes. src/…/MemoryRoutes.ts• L10-15, src/…/MemoryRoutes.ts• L29-45, src/…/MemoryRoutes.ts• L69-116
Because manual saves use the observation path, they enter project-scoped recall and receive the same duplicate and reinforcement treatment as captured knowledge.
References: src/…/MemoryRoutes.ts• L10-15 src/…/MemoryRoutes.ts• L29-45 src/…/MemoryRoutes.ts• L61-116
Memory-item API
The SQLite-backed memory-item API provides direct create, update, search, and context operations for a project. It is suited to structured retained knowledge with fields such as a title, narrative, facts, concepts, and source links. src/…/ServerV1Routes.ts• L183-267, src/…/memory-item.ts• L5-25
This API is separate from the observation importer. Its search and context operations stay within the requested project and use the memory item's indexed content. A context request without a query returns recent project items. It does not apply observation content deduplication or reinforcement, so clients that need those behaviors should use the observation path. src/…/memory-items.ts• L111-149, src/…/memory-items.ts• L181-291, src/…/schema.ts• L85-117
References: src/…/ServerV1Routes.ts• L183-267 src/…/memory-items.ts• L111-149 src/…/memory-items.ts• L181-291 src/…/memory-item.ts• L5-25 src/…/schema.ts• L85-117
Claude Code memory imports
claude-mem memory ingest imports Claude Code topic notes that already contain distilled knowledge. A dry run counts eligible local notes without a database or model call. A real run starts the worker when needed and sends the import to POST /api/memory/ingest. src/…/cli.ts• L22-27, src/…/cli.ts• L44-93, src/…/MemoryIngestRoutes.ts• L16-30
The importer reads topic Markdown files under Claude Code's projects directory. It skips the link-only MEMORY.md index, uses a sibling transcript to resolve the source project when possible, and keeps note metadata as provenance. If no project can be resolved, it uses a best-effort key unless --require-cwd requests a skip. src/…/ingest.ts• L62-73, src/…/ingest.ts• L250-310, src/…/ingest.ts• L327-350, src/…/ingest.ts• L589-617
Each accepted topic file becomes one observation whose body is stored as-is. The importer reports stored, deduplicated, skipped, and failed files separately, so one bad note does not stop the rest of the run. src/…/ingest.ts• L568-587, src/…/ingest.ts• L660-733
The import flow moves from local notes to project assignment and then to durable observation storage:
flowchart LR
A[Claude Code memory notes] --> B[Safe scan and parse]
B --> C[Project and provenance mapping]
C --> D[Mechanical observation store]
D --> E[Stored or deduplicated memory]
References: src/…/cli.ts• L21-93 src/…/MemoryIngestRoutes.ts• L87-120 src/…/ingest.ts• L381-424 src/…/ingest.ts• L646-693
Watched memory files
An optional file bridge turns Markdown files in named memory roots into manual observations. Each root declares its project, which gives file-based ingestion an explicit ownership boundary instead of requiring project discovery. src/…/config.ts• L4-26, src/…/worker-service.ts• L923-932
The bridge polls each root and saves a stable file snapshot after a short quiet period. It reads bounded regular Markdown files, skips links and hidden paths, removes its instruction block, and keeps source files unchanged. An edited file becomes a new memory revision, while a source fingerprint makes repeated scans safe. src/…/file-watcher.ts• L16-20, src/…/file-watcher.ts• L48-87, src/…/save-memory.ts• L30-45
References: src/…/config.ts• L4-31 src/…/file-watcher.ts• L16-20 src/…/file-watcher.ts• L48-87 src/…/worker-service.ts• L923-932
Duplicate detection
Duplicate handling protects the observation stream from retries and repeated confirmation. The system first identifies exact content replays, then can consolidate different text under the same normalized title when Tier-0 deduplication is enabled.
Content identity
An observation's exact identity uses its memory session, title, and narrative. Repeating the same content in the same session resolves to the existing row, which makes import reruns and request retries safe. src/…/SessionStore.ts• L3689-3707, src/…/SessionStore.ts• L3753-3763
The bulk importer checks content identity before reporting a file as newly stored. A changed note can create new content, but an unchanged note is reported as deduplicated. File-based ingestion adds a project-scoped source fingerprint and performs the replay check within the write boundary, so a process retry does not create another observation. src/…/MemoryIngestRoutes.ts• L53-60, src/…/ingest.ts• L660-730, src/…/save-memory.ts• L14-36
References: src/…/store.ts• L1-20 src/…/SessionStore.ts• L3689-3707 src/…/SessionStore.ts• L3753-3763 src/…/MemoryIngestRoutes.ts• L53-60 src/…/save-memory.ts• L14-36
Title-level consolidation
When Tier-0 deduplication is enabled, matching normalized titles within a project can merge new text into an older canonical observation even when the full narratives differ. The canonical row records another occurrence instead of creating a second searchable memory. src/…/SessionStore.ts• L3651-3717
A merged row remains the source of truth for search content and live updates. The new text is not synchronized as if it were stored in the canonical row. src/…/MemoryRoutes.ts• L83-99, src/…/MemoryIngestRoutes.ts• L72-83, src/…/ResponseProcessor.ts• L977-989
References: src/…/SessionStore.ts• L3651-3717 src/…/MemoryRoutes.ts• L83-99 src/…/MemoryIngestRoutes.ts• L72-83 src/…/ResponseProcessor.ts• L977-989
Reinforcement persistence
Reinforcement is a durable record that an existing observation was confirmed again. It lets later context selection use repeated value even when the memory is no longer among the newest records.
Confirmation history
New observations start with their creation day as the first presentation. Exact duplicates and title-level merges add the UTC day of confirmation to the existing row. The history keeps the latest ten distinct days, and another confirmation on the same day does not increase the signal. src/…/persist.ts• L12-41, src/…/strength.ts• L49-72
The history belongs to the local observation database. Older rows without history are not backfilled, so they keep creation-time strength until a later write confirms them. The latest confirmation is also stored as last_reinforced. src/…/SessionStore.ts• L1960-1978
References: src/…/persist.ts• L12-41 src/…/strength.ts• L14-23 src/…/strength.ts• L49-72 src/…/SessionStore.ts• L3650-3654 src/…/SessionStore.ts• L1960-1978
Strength ranking
Session-start context can use reinforcement when CLAUDE_MEM_REINFORCE_ALPHA is above zero. The system then fetches more recent candidates than it finally needs and ranks older candidates by creation recency plus the decayed age of later confirmations. With the default value of zero, it keeps the configured newest observations. src/…/SettingsDefaultsManager.ts• L416-425, src/…/ContextConfigLoader.ts• L57-72, src/…/ObservationCompiler.ts• L42-60
The newest part of the context window stays fixed. Reinforcement chooses only the remaining slots, and the final result returns newest first. This lets a useful old memory re-enter context without hiding current session state. src/…/rank.ts• L64-105
The ranking path connects confirmation history to delivered context:
flowchart LR
A[Duplicate or merge] --> B[Confirmation day]
B --> C[Stored reinforcement history]
C --> D[Wider candidate pool]
D --> E[Strength ranking]
E --> F[Session-start context]
References: src/…/rank.ts• L7-19 src/…/rank.ts• L23-61 src/…/rank.ts• L64-105 src/…/ObservationCompiler.ts• L42-60
Change checklist
When these files or sections are changed, remember to consider these:
- Keep manual-save project precedence aligned with session creation and platform scope. A mismatch can place a memory in a project that recall does not query.
- Keep dry-run file rules aligned with real-import rules. A mismatch can make the preview report the wrong observation count.
- Preserve exact content identity and title-level merge results together. Treating a merge as a new observation can overwrite canonical search content.
- Keep source-fingerprint checks project-scoped and inside the write boundary. Moving either boundary can allow concurrent retries to create duplicates.
- Confirm reinforcement on both exact duplicates and Tier-0 merges. If one path stops confirming rows, ranking can favor the wrong memories.
- Keep the wider candidate pool, fixed recent head, and newest-first output as one contract. Changing one can hide current session state or exclude older useful memories.
- Keep memory-item project and session checks aligned with storage rules. A mismatch can cross project boundaries.
- Keep at least one searchable field on memory-item create and update. Clearing the last indexed field makes an item invisible to search.
- Keep memory-item rows and search entries synchronized. A row without its index entry cannot appear in project search or context.
- Keep watched-root project mappings aligned between file ingestion and native memory lookup. A mismatch can save and search the same file under different projects.
- Keep file revision titles distinct from content fingerprints. Reusing a title can merge an edited file into an older observation.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Import source resolves outside Claude Code's projects directory | The command could retain unrelated files | Resolve the source and symlinks inside the allowed root before scanning |
| A memory note is a symlink or exceeds the size limit | The note is skipped and is not imported | Do not follow symlinks and report skipped files with a reason |
| No sibling transcript resolves the project cwd | Memory can use a best-effort project key and fail to merge with live capture | Use --require-cwd when unresolved projects must be skipped |
| A watched root has no explicit project | File memory can have no safe ownership boundary | Require configured roots with a non-empty project |
| A watched file changes during its read | Partial or outside-root text could enter memory | Validate the path and descriptor around the bounded read |
| A source-fingerprint check runs outside the write boundary | Concurrent retries can create duplicate observations | Perform fingerprint checks within the immediate write transaction |
| A Tier-0 merge is synced as new text | Canonical search content or broadcasts can be overwritten | Skip search sync and broadcast for merged rows |
| Reinforcement ranking uses only the final-size candidate pool | Older confirmed memories cannot outrank newer unconfirmed ones | Fetch the wider pool before ranking |
| A duplicate is confirmed twice on one UTC day | One event can inflate memory strength | Store distinct confirmation days |
| A direct memory-item write has no searchable field | The item is rejected or cannot appear in search | Require content in at least one indexed field |
| A memory item names a session from another project | The write breaks project isolation | Enforce the project-session relationship at the API and storage boundary |
| A memory-item update does not refresh its search entry | Search and context return stale content | Update the SQLite search index with the item |
Key files
| File | Why to read it |
|---|---|
| src/…/ingest.ts | Defines safe Claude Code memory scanning, note mapping, provenance, dry-run counts, and per-file import results. |
| src/…/cli.ts | Shows the command boundary for source selection, dry runs, and worker-backed imports. |
| src/…/MemoryRoutes.ts | Defines the single-memory save API and its project, sync, and merge behavior. |
| src/…/MemoryIngestRoutes.ts | Connects bulk imports to observation storage and reports duplicate outcomes. |
| src/…/file-watcher.ts | Shows how configured Markdown roots become bounded memory revisions. |
| src/…/save-memory.ts | Defines shared file-save replay protection and post-write synchronization. |
| src/…/SessionStore.ts | Shows exact duplicate handling, title-level consolidation, and reinforcement writes. |
| src/…/persist.ts | Defines how confirmation days are stored on observations. |
| src/…/rank.ts | Defines how confirmation history affects context selection. |
| src/…/ObservationCompiler.ts | Shows where optional reinforcement ranking enters session-start context. |
| src/…/ServerV1Routes.ts | Defines the direct memory-item API and its project, content, search, and context rules. |
| src/…/memory-items.ts | Shows memory-item persistence and project-scoped retrieval. |
| src/…/schema.ts | Shows memory-item relationships and search-index maintenance. |