AIPMAndy/dna-memory
AIPMAndy/dna-memory has 102 GitHub stars and 22 forks. GitHot measured -1 stars in 24 hours. Last checked 2026-11-16 19:53 UTC. Last push 2026-11-14.
Measured star growth
- in 24h
- -1
- in 7 days
- Collecting history
- in 15 days
- Collecting history
- in 1 month
- Collecting history
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
Claude Code / Codex 共用的长期记忆 MCP:本地 Markdown/Obsidian 存储,跨工具记住你的项目与偏好|Local-first shared memory MCP for Claude Code & Codex
AIREADME_EN.md
OriginalDNA Memory
A local-first shared memory layer for Codex, Claude, Hermes, and Obsidian
English | 简体中文 | Quick start
DNA Memory uses a Markdown/Obsidian directory as the durable source of truth and SQLite as a disposable, rebuildable index. Codex, Claude Code, Claude Desktop, and Hermes can use the same stdio MCP server instead of keeping conflicting long-term memory copies.
It does not equate storing every conversation with learning. Native transcripts stay in their original clients. DNA Memory stores bounded provenance pointers, reviewable proposals, and verified reusable conclusions.
Core philosophy: from conversation data to reusable cognition
DNA Memory does not treat storing conversations as forming memories. It is a biomimetically inspired cognitive memory system. Cross-client conversations are raw perceptual input; bounded collection, signal extraction, importance and confidence weighting, cognitive classification, verification, recall feedback, and explicit replacement progressively abstract that data into reusable cognition.
It is not another indefinitely growing chat database. Native conversations are source material; only conclusions that have been filtered, verified, and are worth reusing in future work become durable memory.
Core Strategy: Process Memory Before Storing It
DNA Memory is not designed to push more conversation into a database. Its core is a policy loop that gives an agent a human-memory-inspired way to process experience. Conversations are treated as raw perceptual input; only signals that pass the policy gates can become reusable long-term cognition:
- Bound perception: read bounded sources and necessary lifecycle metadata, not complete transcripts as durable memory.
- Filter signals: remove operational talk, transient status, credentials, and conclusions that cannot be reused.
- Weight evidence: combine importance, confidence, provenance, and later usage feedback to decide whether a signal is worth keeping.
- Classify cognition: map signals to preferences, facts, insights, decisions, project state, open loops, workflows, and error lessons.
- Crystallize after verification: write only safe, short, traceable, verified conclusions to the Markdown truth store.
- Recall and learn from feedback: recall before context-dependent tasks;
record
usefulormisleadingonly when the result actually affected work. - Evolve and forget: exact duplicates are collapsed, invalidated cognition
is replaced through explicit
supersedes, and stale pointers are retained only according to bounded retention rules.
This is an engineering strategy inspired by cognitive processes, not a claim to reproduce the human brain. The goal is a repeatable “filter-weight-abstract-verify-recall-correct” loop, rather than an ever-growing chat archive. DNA Memory should be evaluated by whether high-quality cognition is reused correctly, not by how much text it stores.
raw conversations
-> bounded collection and signal extraction
-> importance, confidence, and usage-feedback weighting
-> cognitive classification
-> verified crystallization into durable cognition
-> task-focused recall
-> useful / misleading feedback and supersedes evolution
The current implementation organizes durable cognition into four groups and eight memory types:
| Cognitive model | Memory types | Purpose |
|---|---|---|
| Individual tendencies | preference |
Stable preferences and collaboration habits |
| Facts and insights | fact, insight |
Verified facts and knowledge abstracted from them |
| Decisions and state | decision, project_state, open_loop |
Rationale, current state, and unresolved work |
| Procedures and experience | workflow, error_lesson |
Reusable workflows and verified lessons from failure |
Biomimetics is a design inspiration here, not a claim to replicate the human brain. DNA Memory's value is not how many conversations it stores, but how much high-quality cognition it forms and whether that cognition is accurately recalled and effectively reused in later decisions.
Safety model
- Markdown is durable truth; SQLite is search, queue, and telemetry state.
memory_rememberstores concise conclusions, not transcripts.- Native importers retain IDs, paths, hashes, offsets, and counts by default.
- Automatic extraction produces at most three candidates per session and 800 characters per summary.
- Credential-like content is rejected.
- Cloud-only Claude Desktop chats require explicit MCP writeback when no stable local transcript source is available.
- Memory failure never blocks the primary task.
Install
git clone https://github.com/AIPMAndy/dna-memory.git \
"$HOME/.local/share/dna-memory/app"
cd "$HOME/.local/share/dna-memory/app"
python3 -m venv "$HOME/.local/share/dna-memory/mcp-venv"
"$HOME/.local/share/dna-memory/mcp-venv/bin/pip" install \
-r requirements-mcp.txt
mkdir -p "$HOME/.config/dna-memory" "$HOME/Documents/DNA-Memory-Vault/Memory"
cp docs/profiles/profile.example.json \
"$HOME/.config/dna-memory/profile.json"
The profile stays outside the repository. Adjust the vault and platform Skill roots, then verify the store:
export DNA_MEMORY_PROFILE="$HOME/.config/dna-memory/profile.json"
python3 dna.py memory status --json
python3 dna.py memory reindex --json
Connect Codex, Claude Code, and Hermes
ROOT="$HOME/.local/share/dna-memory/app"
PYTHON="$HOME/.local/share/dna-memory/mcp-venv/bin/python"
PROFILE="$HOME/.config/dna-memory/profile.json"
codex mcp add dna-memory \
--env "DNA_MEMORY_PROFILE=$PROFILE" \
-- "$PYTHON" "$ROOT/scripts/memory_mcp.py"
claude mcp add --scope user dna-memory \
-e "DNA_MEMORY_PROFILE=$PROFILE" \
-- "$PYTHON" "$ROOT/scripts/memory_mcp.py"
hermes mcp add dna-memory \
--command "$PYTHON" \
--env "DNA_MEMORY_PROFILE=$PROFILE" \
--args "$ROOT/scripts/memory_mcp.py"
Verify runtime connectivity, not only configuration text:
codex mcp get dna-memory
claude mcp get dna-memory
hermes mcp test dna-memory
Claude Desktop uses mcpServers with absolute paths. See
client setup for migration, backup, hooks,
importers, and rollback.
MCP tools
| Tool | Purpose |
|---|---|
memory_recall |
Recall active memories for a focused query |
memory_get |
Fetch one memory and its replacement relationships |
memory_remember |
Write a verified durable conclusion |
memory_feedback |
Record useful or misleading recall feedback |
memory_close_session |
Store bounded session provenance |
memory_status |
Inspect truth and index state |
memory_reindex |
Rebuild SQLite from Markdown |
Distribute the bundled dna-memory-loop to each client. It establishes the same behavior everywhere: recall before context-dependent work, give feedback only for used results, and write back only after verification.
Operations
python3 dna.py memory status --json
python3 dna.py memory coverage --json
python3 dna.py memory value --json
python3 dna.py memory reindex --json
python3 dna.py memory maintain daily --json
python3 dna.py memory maintain weekly --json
python3 dna.py memory maintain monthly --json
memory value separates reviewable backlog.reviewable_proposals from
provenance and lifecycle events. backlog.pending is only a compatibility
alias for total_pending; it is not the number of memories awaiting review.
Per-client recall_hits and recall_share show active-recall adoption across
Codex, Claude, and Hermes. Recall share is not a quality score.
In daily maintenance results, crystallized counts newly created durable
memories and deduplicated counts candidates that matched an active memory
with the same type and normalized summary. Duplicate candidates do not create
another Markdown page; their new sources and clients are merged into the
existing provenance fields. Deduplication is exact after normalization, not a
fuzzy similarity merge.
When a new verified fact invalidates an older one, pass exact old memory IDs in
supersedes. Old Markdown remains available as history, while default recall
returns active conclusions only. DNA Memory never infers replacement from type
or project alone.
Bounded native import
python3 scripts/import_codex_rollouts.py
python3 scripts/import_claudian_sessions.py
python3 scripts/import_claude_desktop_sessions.py
python3 scripts/import_hermes_sessions.py
python3 scripts/import_native_history.py
Importers are incremental and idempotent. Ordinary events remain provenance
pointers. Explicit DNA_MEMORY_PROPOSAL {JSON} markers and bounded signal
extraction create review candidates; daily maintenance still applies type,
sensitivity, capacity, and deduplication gates.
After changing native extraction rules, backtest the last seven days in a
separate empty database before bounded production re-extraction. The importer
emits aggregate metrics only, and automatic results remain reviewed
memory_proposal events rather than direct long-term memories:
python3 -m scripts.import_native_history --backtest-days 7 \
--backtest-db /tmp/dna-memory-backtest.db
python3 -m scripts.import_native_history --reextract-days 7
Proceed only when manual sampling finds at most 10% false positives and zero sensitive leakage. Daily maintenance remains the crystallization gate.
Capture is not the same as durable learning. Evaluate both capture coverage and the number of verified memories that are later recalled and marked useful.
Shared Skill management
cp assets/skills.example.json "$HOME/.config/dna-memory/skills.json"
python3 dna.py skills inventory --json
python3 dna.py skills doctor --json
python3 dna.py skills sync --json
python3 dna.py skills sync --apply --json
The registry grants distribution authority only for named Skills. Unregistered
platform-specific Skills are never deleted or overwritten. sync is a dry run
unless --apply is present.
Public release safety
Runtime profiles, databases, native sessions, memory JSON, private Skills, and deployment notes are excluded from source control. Run this before publishing:
python3 scripts/check_public_safety.py
If a credential was ever committed, deleting the current file is insufficient: revoke the credential and clean the Git history.
Validate
python3 -m pytest -q
python3 -m compileall -q dna.py dna scripts tests
python3 scripts/check_public_safety.py
git diff --check