agent-memory-kit

Give your AI coding agent a brain that persists between sessions.

Your agent forgets everything when the conversation ends. agent-memory-kit fixes that. It's a tiered continual memory system — hot memory for instant recall, warm files for project context, and a cognitive engine (CortexDB) that models how human memory actually works: decay, reinforcement, priming, and bias.

Install it. Run agent-memory init. Your agent remembers what it learned yesterday.

What Problem Does This Solve?

Without agent-memory-kit	With agent-memory-kit
Agent asks "what project is this?" every session	Agent reads hot.md — knows your projects, stack, and open threads
Same bugs rediscovered across conversations	Lessons stored in CortexDB, surfaced by context when relevant
No awareness of project architecture	agent-memory onboard ./my-project → full warm file generated
Stale context causes wrong assumptions	Freshness gates flag outdated memory before the agent trusts it
No way to verify agent hallucinated imports	agent-memory scan catches fake imports before they ship
Manual session handoff notes	agent-memory briefing generates context-aware session starts

Quickstart (60 seconds)

pip install agent-memory-kit

# Bootstrap the memory system
agent-memory init

# Check that everything is healthy
agent-memory doctor

# Onboard a project (auto-analyzes architecture, frameworks, deps)
agent-memory onboard ./my-project

# Generate a session briefing from stored knowledge
agent-memory briefing

# Generate a customized agent directive
agent-memory directive --operator "YourName" --review-level "senior engineer" -o AGENT_DIRECTIVE.md

# Check your memory budget
agent-memory status

Want the full walkthrough? See QUICKSTART.md for step-by-step instructions with expected output.

Features

Memory Tiers

• Hot memory (hot.md) — Always-loaded index. Active projects, operator profile, recent lessons, open threads. Max 50 lines, enforced by compaction.
• Warm files (memory/projects/*.md) — Per-project context files with architecture, key files, dependencies, and status. Auto-generated by onboarding.
• Cold archive (archive.md) — Completed projects archived when hot memory is over budget.

Cognitive Engine (CortexDB)

• Ebbinghaus decay — Memories fade over time unless reinforced. Recent, important, frequently-accessed memories surface first.
• Spreading activation — Recalling one memory primes related memories. Ask about "database" and "connection pooling" surfaces too.
• Working memory — Capacity-limited (7±2 items), mimicking human cognitive load constraints.
• Cognitive biases — Models negativity bias (failures remembered more strongly) and recency bias (recent events weighted higher).
• Autobiographical narrative — Long-term episodic memory with temporal context.

Developer Tools

• Onboarding organ — Point it at any codebase. It walks the tree, AST-parses Python/JS/TS, detects frameworks (FastAPI, React, Django, Express, 14+ supported), classifies architecture patterns, maps dependency graphs, and writes a warm file.
• Hallucination scanner — Catches hallucinated imports by validating every import statement against the actual Python environment.
• Freshness gates — Detects when warm files are stale relative to the project they describe. Prevents the agent from trusting outdated context.
• Lesson engine — Self-improving failure memory. Stores hard-won lessons, reinforces on re-encounter, exports to hot memory.
• Session briefing — Generates a context-aware brief from CortexDB for session starts.
• Background daemon — Runs cognitive maintenance (consolidation, decay, trace cleanup) on a schedule.

CLI Commands

Command	What it does
agent-memory init	Scaffold memory directories and starter files
agent-memory doctor	Self-diagnostic — verify install health
agent-memory status	Memory system health and budget usage
agent-memory onboard <path>	Analyze a codebase and generate a warm file
agent-memory freshness	Check warm files for staleness
agent-memory briefing	Generate a session briefing from CortexDB
agent-memory maintain	Run cognitive maintenance (decay, consolidation)
agent-memory scan	Hallucination scanner — find fake imports
agent-memory directive	Generate a customizable agent directive
agent-memory compact	Budget check and optional project archival
agent-memory daemon	Start background maintenance daemon
agent-memory install-service	Install systemd user services

Architecture

agent_memory_kit/
├── config.py               # XDG-respecting path management
├── cli.py                  # Click CLI (12 commands)
├── cortex/                 # CortexDB cognitive engine
│   ├── engine.py           # Core: Cortex, Memory, Ebbinghaus decay
│   ├── priming.py          # Spreading activation
│   ├── autobio.py          # Autobiographical narrative memory
│   ├── cognitive_biases.py # Negativity/recency bias modeling
│   ├── working_memory.py   # Capacity-limited working memory
│   └── trace.py            # Execution trace decorator
├── storage/                # UUID-keyed object store
│   └── engine.py
├── memory_bridge.py        # Flat-file ↔ CortexDB bridge
├── lesson_engine.py        # Self-improving failure memory
├── onboarding.py           # Codebase comprehension organ (750 LOC)
├── compact.py              # Budget enforcement
├── freshness.py            # Warm file staleness detection
├── memory_sync.py          # Auto-update warm files from filesystem
├── subconscious.py         # File change → episodic memory
├── hallucination_scanner.py# Import validation
├── session_briefing.py     # Context-aware session start
├── session_journal.py      # Session continuity
├── maintain.py             # Cognitive housekeeping
├── daemon.py               # Background process orchestrator
└── templates/              # Directive, hot.md, systemd services

Configuration

# Customize the root directory (default: ~/.agent-memory)
export AGENT_MEMORY_HOME=/path/to/memory

# Set project scanning root (default: ~/)
export AGENT_PROJECTS_DIR=/path/to/projects

# Override database path
export AGENT_MEMORY_DB=/path/to/custom.db

How It Integrates With Your Agent

1. Generate a directive with agent-memory directive — this is the system prompt that teaches your agent to use the memory system.
2. Put the directive in your IDE's agent config (e.g., GEMINI.md, .cursorrules, .github/copilot-instructions.md).
3. Your agent now reads hot.md at session start, checks freshness, surfaces relevant lessons, and writes session journals.

The kit is IDE-agnostic. It works with any AI coding agent that can read files and run CLI commands.

Tests

pip install -e ".[dev]"
pytest tests/ -v  # 26 tests

Requirements

• Python ≥ 3.11
• No external cloud dependencies
• No API keys needed
• SQLite (bundled with Python)

License

MIT