agent-mem

Automatic context compression and persistent memory for AI coding agents.

agent-mem helps you keep long coding sessions coherent by capturing decisions, session context, and code signals in structured memory notes. It also generates Obsidian-friendly project graph docs so you can navigate architecture, decisions, blockers, and recent context quickly.

---

Why Use agent-mem

• Preserve critical context between chats and sessions
• Reduce token waste from repeating project history
• Keep technical decisions and blockers traceable
• Generate a searchable Obsidian-native knowledge graph from code + memory

---

How agent-mem Differs

System	Focus	Code-aware	IDE Enforcement	Call Graph	Multi-language	Local-first	Benchmarked
agent-mem	Code session memory	✅	✅ MCP gate + hooks	✅	✅ Python, TS, JS	✅	✅ P/R/F1
mem0	NLP conversation memory	❌	❌	❌	❌	Partial	✅ NLP tasks
Zep	Conversation memory	❌	❌	❌	❌	❌	Limited
MemGPT / Letta	General memory management	❌	❌	❌	❌	✅	✅ NLP tasks
Continue.dev	IDE context window	Partial	❌	❌	Partial	✅	❌
Aider	Context management	Partial	❌	❌	Partial	✅	❌

Key differentiators: agent-mem is the only system that enforces memory loading (MCP session gate + Claude Code UserPromptSubmit hook), extracts call graphs from code, and ships a precision/recall benchmark for its own detection.

---

Core Features

• Smart watch mode with file + git + idle detection
• One-paste handoff prompts (Groq-powered, optional)
• Cross-IDE context migration (agent-mem migrate) for Cursor, Claude (VS Code), and OpenCode
• Obsidian-first storage with wiki-links and YAML frontmatter
• Local fallback mode (.agent-memory/) when Obsidian is not configured
• graph command builds project knowledge docs from code + memory + chat context
• Call graph extraction — tracks which functions call which across the codebase
• Multi-language extraction — Python (AST) + TypeScript/JavaScript (tree-sitter, optional)
• MCP session gate — warns agents that skip query_memory before summarizing
• Claude Code enforcement hook — UserPromptSubmit hook auto-injects memory context every prompt
• Benchmark command — graph benchmark measures extraction Precision/Recall/F1 against ground truth
• Terminal UI — agent-mem tui opens an interactive status/memory/benchmark dashboard
• Incremental graph parse cache for faster rebuilds on unchanged files
• Progress output for large project scans

---

Installation

pip install easy-agent-mem

Optional extras:

pip install 'easy-agent-mem[tui]'       # terminal UI (agent-mem tui)
pip install 'easy-agent-mem[multilang]' # TypeScript/JavaScript extraction via tree-sitter
pip install 'easy-agent-mem[mcp]'       # MCP server support

---

Quick Start

agent-mem init
agent-mem configure-groq      # optional for enrich/watch handoff generation
agent-mem migrate --dry-run cursor .
agent-mem watch               # start automatic handoff mode

After initialization, use agent-mem status to verify storage mode, graph output readiness, and Groq configuration status.

---

How To Use (Practical Flows)

1) First-Time Setup

agent-mem init
agent-mem status
agent-mem setup-vscode            # optional if you want .vscode/mcp.json generated directly
agent-mem configure-groq          # optional, enables watch handoff and graph enrich

2) Daily Memory Workflow

agent-mem checkpoint --stdin
agent-mem prepare-next
agent-mem recall "current goal"

3) Import Context From Other IDE Chats

agent-mem migrate --dry-run cursor .
agent-mem migrate --full cursor claude .

4) Generate Project Knowledge Graph

agent-mem graph build --compact
agent-mem graph build --compact --enrich

5) Automated Handoff Watcher

agent-mem watch --dry-run --once
agent-mem watch

6) MCP / IDE Integration Helpers

agent-mem print-mcp-json
agent-mem serve --force-stdio     # only for debugging MCP startup manually

---

Knowledge Graph (agent-mem graph)

Generate Obsidian-native docs into agent-mem-output/:

agent-mem graph build

Use optional flags:

agent-mem graph build --compact
agent-mem graph build --enrich
agent-mem graph build --compact --enrich
agent-mem graph build --exclude-file-pattern "tests/*" --exclude-file-pattern "**/migrations/*.py"

Common Recipes

# Fast baseline build
agent-mem graph build

# Large repo first pass (trim output size)
agent-mem graph build --compact

# Large repo focused pass (skip low-value paths)
agent-mem graph build --compact \
  --exclude-file-pattern "tests/*" \
  --exclude-file-pattern "**/migrations/*.py" \
  --exclude-file-pattern "**/node_modules/*"

# Semantic pass (requires Groq key)
agent-mem graph build --enrich

Graph Flags

Flag	Description
--compact	Trims long concept/function lists, keeps dashboard/report complete, and writes full lists to agent-mem-output/Full/
--enrich	Adds inferred concepts/relationships via Groq; deterministic graph output is still generated if enrichment fails
--exclude-file-pattern	Excludes files by glob pattern; repeatable and useful for tests/generated/vendor paths

Flag behavior details:

• --compact is ideal for very large repos where full notes are noisy.
• --enrich does not block graph generation; if Groq is unavailable you still get deterministic notes plus actionable diagnostics.
• Multiple --exclude-file-pattern values are combined.
• Patterns match both full relative paths and file names.

Generated Files

• Index.md: dashboard and navigation entrypoint
• Code/*: files, classes, functions, and imports
• Decisions/*: extracted decision and blocker signals
• Sessions/recent-chats.md: active and recent context snippets
• Concepts.md: concept inventory with EXTRACTED / INFERRED labels
• Graph-Report.md: plain-language summary with source breakdown and action suggestions

Open agent-mem-output/Index.md in Obsidian for full navigation and backlinks. The dashboard includes quick navigation links, operational health status, and a direct link back to project root docs.

Enrich Troubleshooting

If --enrich is requested but no inferred output is added, the CLI now prints actionable guidance.

Typical causes and fixes:

• Missing key: run agent-mem configure-groq or export GROQ_API_KEY.
• Invalid key/auth failure: reconfigure key and run agent-mem status.
• Missing client package: install groq (pip install groq).
• Rate limited: retry after a short delay.

Large Project Performance

Graph builds now provide progress updates and incremental parse caching:

• Progress lines show scan stage and running cache-hit/reparse counts.
• Parsed-file cache is stored at agent-mem-output/.graph-cache.json.
• Unchanged Python files are reused from cache on subsequent runs.
• Use --compact and --exclude-file-pattern together for best large-repo responsiveness.

---

Daily Workflow

agent-mem watch
agent-mem migrate --extract-only cursor .
agent-mem checkpoint --stdin
agent-mem prepare-next
agent-mem recall "current goal"
agent-mem graph build --compact

Use this flow to maintain continuity during active implementation and produce graph notes when you need a wider project snapshot.

---

Migration (agent-mem migrate)

Bring context from other IDE chat stores into your current project memory.

What It Does

• Extracts recognizable chat sessions from Cursor, Claude (VS Code), and OpenCode
• Compresses extracted context into agent-mem structured summary format
• In --full mode, saves summary to memory and generates a one-paste handoff prompt
• Writes portable markdown backups under .agent-memory/migrations/
• Supports safe simulation with --dry-run

Source Notes

• cursor: best support on macOS and local .cursor storage
• claude: scans .claude, .vscode, and VS Code workspace storage paths
• opencode: scans local .opencode and common OpenCode config paths
• antigravity: best-effort extraction only (depends on local transcript format)

Examples

agent-mem migrate
agent-mem migrate cursor .
agent-mem migrate --extract-only cursor claude .
agent-mem migrate --full cursor claude .
agent-mem migrate --dry-run cursor .
agent-mem migrate --full cursor .
agent-mem migrate --dry-run --full cursor claude opencode .

Modes

• --extract-only: extract + backup only (default for direct CLI usage)
• --full: extract + save summary to memory + generate handoff + backup
• --dry-run: no file writes, prints preview summary/handoff output

Recommended Workflow

# 1) Preview what will be extracted
agent-mem migrate --dry-run cursor .

# 2) Persist memory + handoff prompt for actual continuation
agent-mem migrate --full cursor .

# 3) Paste the generated handoff prompt into your active IDE chat
#    and let the agent write a fresh structured summary.

Output Artifacts

• Memory summary:
  • Obsidian mode: Memory/Agent-Mem/<project>-<timestamp>-session.md
  • Fallback mode: .agent-memory/memory.md
• Handoff outbox: .agent-memory/outbox/latest-handoff.md
• Migration backup: .agent-memory/migrations/<timestamp>-<sources>.md

---

Commands Overview

Setup and Configuration

Command	Description	Example
agent-mem init	Interactive first-time setup for storage + IDE instruction files + MCP config hints	agent-mem init
agent-mem setup	Re-run instruction + MCP config setup for current project	agent-mem setup
agent-mem setup-vscode	Write .vscode/mcp.json with detected/selected Python interpreter	agent-mem setup-vscode --python /path/to/python3
agent-mem print-mcp-json	Print MCP JSON block for manual paste into IDE config	agent-mem print-mcp-json
agent-mem configure-groq	Save Groq API key and optional model	agent-mem configure-groq --model llama-3.3-70b-versatile
agent-mem status	Show storage mode, graph readiness, and Groq status	agent-mem status

Memory and Continuity

Command	Description	Example
agent-mem summarize	Save a structured session summary into memory	agent-mem summarize --summary-file summary.md
agent-mem checkpoint	Update compact active handoff context file	agent-mem checkpoint --stdin
agent-mem prepare-next	Print starter block for a fresh follow-up chat	agent-mem prepare-next
agent-mem recall <query>	Search saved memory for relevant context	agent-mem recall "current blockers"

Migration

Command	Description	Example
agent-mem migrate	Extract and convert IDE chat history into summaries/handoff/backups	agent-mem migrate --full cursor claude .

Graph

Command	Description	Example
agent-mem graph build	Generate knowledge graph notes and dashboard	agent-mem graph build --compact --exclude-file-pattern "tests/*"
agent-mem graph benchmark	Measure extraction Precision/Recall/F1 against fixture ground truth	agent-mem graph benchmark --fixtures-dir tests/fixtures

Terminal UI

Command	Description	Example
agent-mem tui	Open interactive terminal dashboard (Status / Memory / Benchmark tabs)	agent-mem tui

Watch Mode and Handoff Automation

Command	Description	Example
agent-mem watch	Monitor repo activity and generate handoff prompts automatically	agent-mem watch --once --dry-run
agent-mem test-watch	Trigger one immediate handoff generation without waiting for file events	agent-mem test-watch --dry-run

MCP Server

Command	Description	Example
agent-mem serve	Start MCP stdio server (normally launched by IDE, not by hand)	agent-mem serve --force-stdio

---

Storage Modes

Obsidian Mode

If Obsidian is configured, notes are written under:

• Memory/Agent-Mem/ for session and active context notes
• agent-mem-output/ for graph notes

Local Fallback Mode

If Obsidian is unavailable, memory is written to:

• .agent-memory/active.md
• .agent-memory/memory.md

---

Troubleshooting

• If --enrich does not apply inferred content, run agent-mem status and verify Groq key/model configuration.
• If graph output is too large, use --compact.
• For large repos, exclude low-value paths with repeatable --exclude-file-pattern options.

---

What's Fixed in 0.7.2

Ten reliability bugs fixed across the core modules.

#	Module	Bug	Fix
1	memory.py	Obsidian session glob used raw project name — never matched any file	Changed to _slug(project_name) to match how session files are written
2	lang_parsers.py	Arrow function records duplicated — lexical_declaration fell through to unconditional child walk	Added return after handling, matching the class_declaration pattern
3	watcher.py	Obsidian users always got empty recent_memory in handoff prompts — fallback file is empty in Obsidian mode	Now reads recent Obsidian session files via list_recent_session_files when Obsidian enabled
4	mcp_server.py	_session state bled across MCP connections — memory_loaded=True from one caller persisted to the next	Reset memory_loaded at start of query_memory and after summarize_to_obsidian
5	migrator.py	Candidate file sort prioritised recency over relevance — low-score stale files could beat fresh matches	Sort key flipped to (score, mtime) so relevance wins, recency is tiebreaker
6	migrator.py	.vscode included in Claude extraction roots — scanned editor config JSON as chat transcripts	Removed .vscode from roots; only .claude and system storage paths are scanned
7	mcp_server.py	list_recent_sessions ignored count param in fallback mode — always returned one file regardless	Now uses the files list returned by list_recent_session_files, which already respects count
8	watcher.py	git diff --numstat missed staged changes — watcher saw 0 diff lines when all changes were staged	Changed to git diff HEAD --numstat which covers both staged and unstaged
9	memory.py	Dead condition "." not in match in _extract_file_links — regex guarantees a . is always present	Removed the unreachable branch
10	config.py	Module-level CONFIG_DIR/CONFIG_FILE reassigned on every call via global — dead assignments	Removed module-level globals and global statements; functions use local vars

---

Project Links

• PyPI: easy-agent-mem
• GitHub: atharvavdeo/agent-mem

---

License

MIT