Memory Inheritance

A new AI session should feel like a developer continuing work,
not a new developer joining the project from zero.

npx mem-extract init

---

The Problem

Every time you start a new session with Claude Code, Codex, or Cursor, your AI agent starts from zero.

It doesn’t know:

• What you’re currently building
• Why you made certain architecture decisions
• What constraints you’re working under
• What you tried last time and why it didn’t work

You spend the first 10 minutes of every session re-explaining your project. That’s not a workflow. That’s repeated onboarding.

---

The Solution

Memory Inheritance generates and maintains a persistent, human-readable memory system inside your repository.

Your AI agent reads it at the start of every session. No re-explaining. No context drift. No forgotten decisions.

Git remembers code history.
Memory Inheritance remembers project context.

---

Why Human-Controlled Memory

Most AI memory tools auto-capture everything and store it in a database.

Research says this is the wrong approach.

A 2025 study by UIUC and Tsinghua University, “Useful Memories Become Faulty When Continuously Updated by LLMs”, found that AI agents that frequently auto-update their memory perform worse over time — not better. Automated memory accumulation introduces noise, conflicts, and degraded context quality.

Memory Inheritance takes the opposite approach:

• You decide what gets remembered — no background daemons, no auto-capture
• Memory lives in Markdown — human-readable, editable, version-controlled
• Safe sync markers — auto-generated sections never overwrite your manual notes
• Review command — check if your memory is actually good enough before trusting an agent with your project

---

Quick Start

# Initialize memory in your project
npx mem-extract init

# Check if your memory is ready for AI handoff
npx mem-extract review

# Update memory with recent Git activity
npx mem-extract sync --recent 10

# Check current memory status
npx mem-extract status

That’s it. Your AI agent now has persistent project context.

---

What Gets Generated

your-project/
├── PROJECT_MEMORY.md        ← canonical project memory
├── CLAUDE.md                ← Claude Code adapter
├── AGENTS.md                ← Codex / generic agent adapter
└── .memory/
    ├── index.json           ← metadata routing index
    └── modules/             ← detailed memory loaded on demand
        ├── cli.md
        ├── git-memory.md
        └── ...

PROJECT_MEMORY.md

The canonical memory file your agents read at session start. Contains:

• Project overview and current development state
• Architecture decisions — why things are built the way they are
• Manual notes — constraints and context invisible in the code
• AI collaboration rules
• Recent Git development memory

Human-written sections are never overwritten by sync. Only auto-generated sections inside markers get updated.

CLAUDE.md / AGENTS.md

Lightweight adapter files that instruct each AI tool to load memory correctly. Claude Code reads CLAUDE.md. Codex and other agents read AGENTS.md.

.memory/index.json

A metadata routing index. Instead of loading every memory file every session, agents read the index and load only what’s relevant to the current task — reducing token waste.

---

Memory Readiness Review

Generating memory files doesn’t guarantee useful context. A project can have all the right files and still leave an agent completely lost.

npx mem-extract review

Memory Readiness Review
────────────────────────────────────────

Status: 🟡 Usable — agent can work, but has blind spots

Structure
  🟢 PROJECT_MEMORY.md exists
  🟢 CLAUDE.md exists
  🟢 AGENTS.md exists

Context Richness
  🔴 Current Development State is empty
     → Agent won't know what you're currently working on
  🔴 Manual Notes is empty
     → Agent won't know hidden project constraints
  🟡 Architecture Decisions has very little content
     → Agent may remove intentional design choices

Freshness
  🟡 Git memory is 9 days old
     → Agent may be working from outdated context

────────────────────────────────────────
Suggested next steps:
  1. Fill in Current Development State
  2. Fill in Manual Notes
  3. Run: npx mem-extract sync --recent 10

Three readiness levels:

• 🟢 Ready — agent can take over immediately
• 🟡 Usable — agent can work, but has blind spots
• 🔴 Incomplete — agent will frequently ask basic questions

Machine-readable output also available:

npx mem-extract review --json

---

All Commands

npx mem-extract init                        # initialize memory system
npx mem-extract sync                        # update project scan memory
npx mem-extract sync --recent 10            # also update Git memory
npx mem-extract review                      # check AI handoff readiness
npx mem-extract review --json               # machine-readable review output
npx mem-extract status                      # show memory file status
npx mem-extract inspect <section>           # read a memory section
npx mem-extract inspect ref:<id>            # read a specific memory module
npx mem-extract score <id> <score>          # set module criticality (1-10)
npx mem-extract score list                  # list all criticality scores
npx mem-extract score explain               # explain scoring system

---

Token-Aware Design

Bad memory design: agent loads everything on every session.

Memory Inheritance design:

1. Agent reads CLAUDE.md or AGENTS.md
2. Adapter points to PROJECT_MEMORY.md
3. PROJECT_MEMORY.md provides compact canonical context
4. If more detail is needed, agent consults .memory/index.json
5. Agent loads only the relevant module
6. Criticality scores tell agent what to prioritize when context is tight

This keeps token usage proportional to task complexity.

---

Design Philosophy

Local-first          No external APIs, no cloud sync, no background services
Deterministic        Same inputs produce same outputs
Human-editable       Memory files are plain Markdown — read and edit them directly
AI-readable          Structured for agent consumption, not just human documentation
Token-aware          Routing index prevents loading everything every session
Safe for manual notes Human-written content is never overwritten by sync

Memory Inheritance is not:

• an autonomous agent runtime
• a background daemon
• an AI operating system
• a swarm orchestration framework
• a replacement for human judgment

---

Compared to Auto-Capture Tools

	Auto-capture tools	Memory Inheritance
Memory source	AI auto-extracts from conversations	Developer decides what matters
Storage	Database (opaque)	Markdown (transparent)
Human-editable	No	Yes
Background daemon	Yes	No
External API required	Often	Never
Memory quality check	None	review command
Research-backed	Contradicted by UIUC/Tsinghua study	Aligned with findings

---

Supported Agents

Works with any AI coding tool that reads project files:

• Claude Code — via CLAUDE.md
• Codex CLI — via AGENTS.md
• Cursor — via AGENTS.md
• Gemini CLI — via AGENTS.md
• GitHub Copilot — via .github/copilot-instructions.md (coming soon)
• Any agent — that reads Markdown files in the project directory

---

License

MIT