Introducing a new way to review your PRs.

Read the announcement

thedotmack / claude-mem

Persistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More

View on GitHub

47 documents · Updated Nov 20, 2026

docs / memory-ingest-and-reinforcement

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

TriggerConsequenceGuard
Import source resolves outside Claude Code's projects directoryThe command could retain unrelated filesResolve the source and symlinks inside the allowed root before scanning
A memory note is a symlink or exceeds the size limitThe note is skipped and is not importedDo not follow symlinks and report skipped files with a reason
No sibling transcript resolves the project cwdMemory can use a best-effort project key and fail to merge with live captureUse --require-cwd when unresolved projects must be skipped
A watched root has no explicit projectFile memory can have no safe ownership boundaryRequire configured roots with a non-empty project
A watched file changes during its readPartial or outside-root text could enter memoryValidate the path and descriptor around the bounded read
A source-fingerprint check runs outside the write boundaryConcurrent retries can create duplicate observationsPerform fingerprint checks within the immediate write transaction
A Tier-0 merge is synced as new textCanonical search content or broadcasts can be overwrittenSkip search sync and broadcast for merged rows
Reinforcement ranking uses only the final-size candidate poolOlder confirmed memories cannot outrank newer unconfirmed onesFetch the wider pool before ranking
A duplicate is confirmed twice on one UTC dayOne event can inflate memory strengthStore distinct confirmation days
A direct memory-item write has no searchable fieldThe item is rejected or cannot appear in searchRequire content in at least one indexed field
A memory item names a session from another projectThe write breaks project isolationEnforce the project-session relationship at the API and storage boundary
A memory-item update does not refresh its search entrySearch and context return stale contentUpdate the SQLite search index with the item

Key files

FileWhy to read it
src/…/ingest.tsDefines safe Claude Code memory scanning, note mapping, provenance, dry-run counts, and per-file import results.
src/…/cli.tsShows the command boundary for source selection, dry runs, and worker-backed imports.
src/…/MemoryRoutes.tsDefines the single-memory save API and its project, sync, and merge behavior.
src/…/MemoryIngestRoutes.tsConnects bulk imports to observation storage and reports duplicate outcomes.
src/…/file-watcher.tsShows how configured Markdown roots become bounded memory revisions.
src/…/save-memory.tsDefines shared file-save replay protection and post-write synchronization.
src/…/SessionStore.tsShows exact duplicate handling, title-level consolidation, and reinforcement writes.
src/…/persist.tsDefines how confirmation days are stored on observations.
src/…/rank.tsDefines how confirmation history affects context selection.
src/…/ObservationCompiler.tsShows where optional reinforcement ranking enters session-start context.
src/…/ServerV1Routes.tsDefines the direct memory-item API and its project, content, search, and context rules.
src/…/memory-items.tsShows memory-item persistence and project-scoped retrieval.
src/…/schema.tsShows memory-item relationships and search-index maintenance.