agent-mem

Automatic context compression and persistent memory for AI coding agents.

agent-mem saves coding decisions, constraints and session context so you can continue work across chats. Search previous decisions, check whether their supporting files have changed, and carry relevant context into your next session.

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

Core Features

• Save decisions, constraints and blockers with their sources and supporting files
• Check saved decisions for changed or missing evidence
• Retrieve relevant context with citations and a token budget
• Keep memory separate across repositories, branches, worktrees and sessions
• Resume sessions with durable handoffs and explicitly share selected records
• Track review findings, fixes, verification results and failed approaches
• Export structured memory to Markdown or Obsidian
• 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

Installation

pip install easy-agent-mem

# Install 0.8.0 from GitHub
pip install "git+https://github.com/atharvavdeo/agent-mem.git@v0.8.0"

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
pip install 'easy-agent-mem[context] @ git+https://github.com/atharvavdeo/agent-mem.git@v0.8.0' # token counting

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) Import Context From Other IDE Chats

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

3) Generate Project Knowledge Graph

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

4) Automated Handoff Watcher

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

5) 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"

Graph Flags

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

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

Commands Overview

Setup and Configuration

Memory and Continuity

Migration

Graph

Terminal UI

Watch Mode and Handoff Automation

MCP Server

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
• .agent-memory/engineering/ for structured session records

Set AGENT_MEM_STORAGE_DIR to use a different local directory for structured memory.

What's Fixed in 0.8.0

Project Links

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

License

MIT