ai-memory

Overview

ai-memory is a lightweight, cross-vendor long-term memory solution designed specifically for AI agent CLIs and coding assistants. With approximately 3,000 GitHub stars, ai-memory addresses one of the most persistent pain points in the agent ecosystem: context loss across sessions and between different AI tools.

Unlike session-local memory that resets with every conversation, ai-memory persists across sessions, vendors, and even tools. If you use Claude Code for one task, GitHub Copilot for another, and Cursor for a third, ai-memory maintains a coherent memory graph that all three can access. It's designed to be the "shared memory bus" for multi-tool agent workflows.

The project emerged from the observation that most developers today use multiple AI coding tools simultaneously, but each tool maintains its own isolated memory. ai-memory bridges this gap with a vendor-neutral storage format and a thin adapter layer for each supported tool.

Features

• Cross-vendor memory: Single memory store accessible by Claude Code, Cursor, Copilot, and other agent CLIs
• Session persistence: Memory persists across CLI sessions, restarts, and tool switches
• Graph-based structure: Memories are linked as a knowledge graph, not flat key-value pairs
• Automatic capture: Hooks into agent tool calls to capture relevant context automatically
• Manual management: CLI commands to manually add, search, edit, and delete memories
• Semantic search: Vector-based retrieval for natural-language memory queries
• Privacy-first: Local-first storage; no cloud dependencies or telemetry
• Format portable: Memory exports in standard JSON/Markdown for backup and migration
• Scoped memories: Per-project, per-user, and global memory scopes
• Versioned: Memory changes are tracked and reversible

Installation

# Install via npm
npm install -g ai-memory

# Or via pip (Python CLI)
pip install ai-memory

# Verify installation
ai-memory --version

Quick Start

# Initialize memory for a project
cd ~/my-project
ai-memory init

# Add a memory manually
ai-memory add "User prefers TypeScript over JavaScript for new projects" --scope project

# Search memories
ai-memory search "What languages does this project use?"

# List all memories in the project scope
ai-memory list --scope project

# Set up automatic capture for Claude Code
ai-memory hook claude-code --install

# Set up automatic capture for Cursor
ai-memory hook cursor --install

Programmatic Usage (Python)

from ai_memory import MemoryGraph

# Connect to the project memory store
memory = MemoryGraph(path="./.ai-memory/graph.db")

# Add a memory with relationships
memory.add(
    content="Project uses FastAPI with SQLAlchemy",
    scope="project",
    tags=["backend", "python"],
    relates_to=["architecture", "tech-stack"],
)

# Query memories
results = memory.search("What is the backend stack?")
for r in results:
    print(f"{r.content} (confidence: {r.score:.2f})")

# Export for backup
memory.export("backup-2026-08-19.json")

Core Concepts

Memory Graph

Memories in ai-memory are nodes in a graph, connected by edges that represent relationships:

• Temporal edges: "Memory A was added before Memory B"
• Semantic edges: "Memory A is related to Memory B"
• Source edges: "Memory A was captured from Claude Code session X"
• Importance edges: "Memory A reinforced Memory B"

This graph structure enables sophisticated queries like "find all preferences the user expressed that relate to Python development."

Scopes

Three scope levels control memory visibility:

• global: Available to all projects and users (e.g., personal coding preferences)
• user: Available across all projects for the current user
• project: Available only within the current project directory

Vendors

ai-memory supports the following agent CLIs out of the box:

• Claude Code
• Cursor
• GitHub Copilot CLI
• OpenInterpreter
• Windsurf
• Roo Code
• Kimi Code CLI

Custom vendors can be added via a simple adapter interface.

Advanced Features

Automatic Context Injection

When a supported agent CLI launches, ai-memory automatically injects relevant memories into the context:

# Enable auto-injection for Claude Code
ai-memory hook claude-code --enable-injection

# Configure injection parameters
ai-memory config set injection.max-memories 10
ai-memory config set injection.relevance-threshold 0.7

Cross-Session Continuity

ai-memory tracks session boundaries and automatically summarizes long sessions:

# Get a summary of all memories added in the last 7 days
summary = memory.summarize(period="7d", scope="project")
print(summary)
# "In the past 7 days: switched to FastAPI, added Redis for caching,
#  user prefers pydantic v2 over v1, decided on Postgres for main DB"

Memory Conflicts

When two memories contradict each other (e.g., "user prefers TypeScript" and "user prefers JavaScript"), ai-memory flags the conflict and defers to the most recent memory by default:

ai-memory conflicts
# Potential conflict: "prefers TypeScript" vs "prefers JavaScript"
# Resolution: Most recent (2026-08-15) wins

# Resolve manually
ai-memory resolve --id mem-123 --keep "prefers TypeScript"

Examples

Example 1: Shared Memory Across Tools

# In Claude Code session
ai-memory add "Project uses SQLite for development, PostgreSQL for production"

# Switch to Cursor — memory is accessible
# Cursor reads: "Project uses SQLite for development, PostgreSQL for production"

Example 2: Project Onboarding

# New team member joins
ai-memory export --format markdown --output ONBOARDING.md
# Produces a structured onboarding doc from accumulated memories

Example 3: Custom Hook for a New Agent

from ai_memory.hooks import BaseHook

class MyAgentHook(BaseHook):
    name = "my-agent"
    
    def on_start(self):
        memories = self.memory.search("relevant context for current task", top_k=5)
        return memories
    
    def on_tool_call(self, tool_name, args):
        # Capture tool call results as memories
        self.memory.capture(tool_name, args)

Pros

• ✅ Cross-vendor: Unlocks memory sharing across multiple AI tools
• ✅ Local-first: No cloud dependencies, no telemetry, privacy-preserving
• ✅ Lightweight: Minimal footprint, fast startup, low resource usage
• ✅ Graph-based: Sophisticated memory relationships, not just flat storage
• ✅ Automatic capture: Integrates with agent CLI workflows transparently
• ✅ Scoped and versioned: Fine-grained control over memory visibility and history
• ✅ Portable format: Easy to backup, export, and migrate

Cons

• ❌ Very small community: ~3K stars, still early-stage
• ❌ Coverage gaps: Not all agent CLIs have adapters yet
• ❌ Conflict resolution is basic: More sophisticated resolution strategies needed
• ❌ Manual setup: Requires per-project initialization and hook installation
• ❌ No real-time sync: Multi-device sync not yet supported
• ❌ Learning curve: Graph-based memory model is unfamiliar to many developers

When to Use

• Using multiple AI coding tools: If you switch between Claude Code, Cursor, Copilot, etc., ai-memory keeps context coherent
• Building persistent agent products: When your agent needs to remember user preferences across sessions
• Privacy-sensitive environments: When cloud-based memory solutions are not acceptable
• Team onboarding: Export accumulated project memories as onboarding documentation
• Long-running projects: When context accumulation becomes valuable over time

Resources

• GitHub Repository
• Documentation

Related Projects

• Mem0 — AI memory for applications
• TencentDB-Agent-Memory — Fully local long-term memory for agents
• codebase-memory-mcp — Sub-millisecond code intelligence
• Zep — Long-term memory server