agent-memory

Persistent memory & cross-agent orchestration for AI coding agents.

Works with Claude Code, Cursor, GitHub Copilot, Codex, and Gemini Code Assist. Any AI coding agent.

---

The Problem

Every AI coding session starts from zero.

You explained the same auth architecture to Claude last week. You debugged that SQLite schema with Cursor two weeks ago. You made a key design decision in Copilot yesterday. Gone.

Your agents have no memory. You're the only one who remembers — and you can't be in every session at once.

The Solution

agent-memory gives your AI coding agents persistent, searchable memory — stored in your own Git repository, working across all agents and all devices. Free, private, no cloud required.

Session ends → summary + metadata → Git commit
Session starts → relevant past sessions → injected into context

You keep your data. Your agents keep their memory.

---

Quick Start

npx agent-memory init

That's it. agent-memory detects your installed agents, imports your existing sessions, and is ready to search in under 30 seconds.

agent-memory v0.1.0

Detected agents:
  ✓ Claude Code    (terminal)   — 142 sessions
  ✓ ChatGPT        (web export) — 38 sessions
  ✓ Gemini         (web export) — 17 sessions

Import 197 existing sessions? [Y/n]
Importing sessions... done. 197 imported.

✓ Ready. Try: agent-memory search "authentication refactoring"

---

Search Your Past Sessions

agent-memory search "JWT to session token migration"

#1  [2026-03-15] Claude Code — 45min — debugging, auth
    "Migrated JWT auth to session tokens. Redis considered but SQLite chosen for single-server."
    Files: src/auth/login.ts, src/db/schema.ts

#2  [2026-03-10] Cursor — 22min — refactoring
    "Refactored token validation middleware. Added session expiry check."
    Files: src/middleware/auth.ts

#3  [2026-02-28] Claude Code — 90min — architecture
    "Designed auth architecture. Evaluated JWT vs session tokens vs OAuth."
    Files: docs/auth-design.md

---

Features

Feature	Status
Automatic session ingestion (Claude Code)	✅ M0
Cross-agent import (ChatGPT, Gemini export)	✅ M0
Hybrid search (FTS5 + RRF time decay)	✅ M0
Git-native sync (cross-device)	🔜 M1
Dense embedding search (ONNX, offline)	🔜 M1
P2P agent orchestration	🔜 M1
VS Code / Cursor extension	🔜 M1

---

Install

# One-time setup
npx agent-memory init

# With Claude Code auto-ingestion hooks
npx agent-memory init --claude-code

# Import ChatGPT history
npx agent-memory init --chatgpt-export ~/Downloads/conversations.json

# Import Gemini history (Google Takeout)
npx agent-memory init --gemini-takeout ~/Downloads/Takeout/Gemini\ Apps\ Activity

Requirements

• Node.js >= 18
• Claude Code, Cursor, VS Code, or any AI coding agent

---

CLI Reference

agent-memory init              # Set up + import existing sessions
agent-memory search <query>    # Hybrid search across all sessions
agent-memory status            # Health check + statistics
agent-memory ingest            # Manually ingest latest session (used by hooks)
agent-memory forget <id>       # Delete a session (GDPR)

---

How It Works

Session Ingestion

When a Claude Code session ends, the SessionEnd hook fires:

agent-memory ingest --platform claude-code
  → reads ~/.claude/projects/{project}/{session_id}.jsonl
  → extracts: files touched, tools used, duration, model
  → infers categories (debugging, refactoring, auth, ...)
  → stores in ~/.local/share/agent-memory/sessions.db

For ChatGPT and Gemini, import your export once and agent-memory indexes the conversations locally.

Search

Hybrid search with time decay:

Query → FTS5 (BM25, trigram tokenizer for CJK+English)
      + RRF fusion
      + Time decay (λ=0.023, ~30-day half-life)
      + Hit boost (frequently referenced sessions surface higher)
→ Top 5 results with metadata

Privacy

• Your data stays local. sessions.db lives at ~/.local/share/agent-memory/ — outside any Git repository.
• No conversation content is stored. Only metadata: date, duration, file paths, tool names, inferred categories.
• Sensitive paths are excluded automatically. .env, .ssh/, credentials, *.pem are filtered before storage.
• Delete any session: agent-memory forget <session-id>

---

Cross-Agent Support

Agent	Ingestion	Import
Claude Code	Automatic (SessionEnd hook)	✅ existing sessions
ChatGPT	Manual export	✅ conversations.json
Gemini	Manual export	✅ Google Takeout
Cursor	🔜 M1 (file watcher)	—
VS Code / Copilot	🔜 M1 (extension)	—
Codex	🔜 M1 (CLI wrapper)	—

---

Architecture

agent-memory
  ├── Core
  │   ├── sessions.db        — SQLite WAL, FTS5 index (local, outside Git)
  │   └── Adapters           — Read logs from Claude Code, ChatGPT, Gemini
  ├── Search
  │   ├── FTS5               — Trigram tokenizer (CJK + English)
  │   └── RRF                — Time decay + hit boost fusion
  └── CLI
      └── init / search / status / ingest / forget

Data directory: ~/.local/share/agent-memory/ (macOS/Linux), %LOCALAPPDATA%\agent-memory\ (Windows)

---

Contributing

See CONTRIBUTING.md.

The easiest first contribution: add a platform adapter for a new agent (Codex, Windsurf, etc.).

Each adapter implements a simple interface:

interface PlatformAdapter {
  platform: string;
  detect(): boolean;
  listSessions(since?: Date): RawSession[];
}

---

Roadmap

• M1: Git sync, dense embedding (ONNX, offline), P2P orchestration, Cursor/VS Code extension
• M2: Ed25519 session signing, SQLCipher encryption, Web dashboard
• v1.0: API stability, semver guarantee, Codex/Gemini extension

---

License

Apache 2.0 — see LICENSE.