crossmem 1.9.1

Cross-project memory for AI coding agents

Your AI tools forget. crossmem doesn't.

Cross-tool memory for AI coding agents. One pip install, zero cloud, zero accounts — your Claude Code, GitHub Copilot, and Gemini CLI sessions remember everything, across every project, automatically.

Quick start

pip install crossmem        # 1. Install
crossmem setup              # 2. Done. All tools configured.

That's it. Every AI coding session now starts with cross-project context.

Why crossmem?

Every AI coding session starts cold. The model re-asks the same setup questions, re-derives the same patterns, re-reads the same files — because it has no memory of what you worked through last time.

We measured the impact using tokenxray across real Claude Code sessions before and after installing crossmem:

Metric	Delta
Avg input tokens / session	−74%
Avg cost / session	−83%
Cache hit rate	+18%
Avg turns to reach result	−60%

Measured across real sessions. Results vary by project size and task type.

crossmem fixes this by injecting remembered context before the AI starts thinking — not as a suggestion it can ignore, but as enforced context.

You: "How should I handle credentials in this new service?"

AI: [crossmem recalls patterns from 3 of your projects]
    Based on your backend-api, mobile-app, and infra-tools projects,
    you use a middleware layer for credential masking — keys in
    Secret Manager, never env vars, masked in logs via
    _mask_sensitive_headers(). Applying the same pattern here.

No copy-pasting. No "I already solved this." Your AI remembers — across every project.

How it differs

	crossmem	Mem0	Letta	Zep
Install	pip install + SQLite	Cloud API key or self-hosted Qdrant	Server + Docker	Postgres + Go server
Cross-tool	Claude + Copilot + Gemini	Single app	Single app	Single app
Cross-project	All projects, one index	Per-app scoped	Per-agent scoped	Per-session scoped
Protocol	MCP-native	REST API	Custom framework	SDK
Infrastructure	None. Local SQLite.	Cloud or Qdrant + server	Letta server	Postgres + server
Enforcement	Hook injects context before generation	LLM decides to call API	LLM self-manages memory	LLM calls SDK

Works with

Tool	Auto-recall	How
Claude Code	SessionStart hook (startup/resume/compact) + UserPromptSubmit hook (every prompt)	crossmem install-hook
GitHub Copilot	Injects memories into copilot-instructions.md	crossmem install-hook --tool copilot
VS Code Agent Mode	SessionStart + UserPromptSubmit hooks (Preview)	crossmem install-hook --tool copilot-agent
Gemini CLI	Instruction in GEMINI.md	crossmem install-instructions

What happens under the hood

cd ~/any-project
claude                    # Claude Code: hook fires, memories injected automatically
code .                    # Copilot: reads context pre-injected into copilot-instructions.md
gemini                    # Gemini: calls mem_recall via instruction in GEMINI.md

1. Auto-ingest — pulls latest memories from Claude, Copilot, and Gemini native files
2. Auto-init — first time in a project? Indexes README.md, CLAUDE.md, etc.
3. Tiered recall — returns most relevant context within a token budget: curated memories > tool memories > CLAUDE.md > CONTRIBUTING.md > README.md
4. Mid-session recall (Claude Code + VS Code Agent Mode) — every prompt is searched against your memories. Relevant context is injected before the model responds — no manual mem_recall needed.
5. Learn — AI saves new discoveries via mem_save during sessions. Knowledge compounds. Each memory is written as a durable .md file to ~/.crossmem/memories/<project>/ — the DB is rebuilt from these files on startup, so memories survive a clean install.
6. Freshness tracking (v1.3.0) — every memory carries a last_verified timestamp. mem_recall and mem_search surface [verified: YYYY-MM-DD] or [unverified] next to each result so agents can judge trust level at a glance. Use mem_verify(id) to stamp a memory as confirmed without changing its content.
7. Smart search (v1.1.0) — a two-layer noise filter separates signal tokens from noise before every FTS query. Layer 1 excludes 168 linguistically fixed closed-class words (prepositions, pronouns, auxiliaries, etc.) in O(1). Layer 2 applies corpus-adaptive IDF via FTS5 — tokens that appear in more than 40% of your documents are treated as project-specific noise. Zero additional dependencies.
8. Scope model (v1.2.0) — memories are either project-scoped (visible only within their project) or global (surfaced everywhere). Memories saved identically across 2+ projects are automatically promoted to global via auto_promote_patterns().

MCP Server

Add to your tool's MCP config so AI assistants can search, recall, and save memories in real-time:

Claude Code (~/.mcp.json)

{
  "mcpServers": {
    "crossmem": {
      "command": "crossmem-server"
    }
  }
}

GitHub Copilot (.vscode/mcp.json)

{
  "servers": {
    "crossmem": {
      "command": "uvx",
      "args": ["--from", "crossmem", "crossmem-server"]
    }
  }
}

Gemini CLI (~/.gemini/settings.json)

{
  "mcpServers": {
    "crossmem": {
      "command": "crossmem-server"
    }
  }
}

If crossmem-server isn't on PATH, use uvx --from crossmem crossmem-server instead.

MCP Tools

Tool	Description
mem_recall	Load project context + cross-project patterns at session start
mem_search	Search across all memories (query, project filter, limit)
mem_save	Save a discovery during a session (writes a durable .md file + DB row)
mem_update	Update a memory in place (preserves ID, syncs backing file)
mem_forget	Delete a memory by ID (removes backing file from disk)
mem_get	Get full content of a memory by ID
mem_verify	Mark a memory as verified today (no content change)
mem_promote	Promote a project-scoped memory to global scope
mem_demote	Demote a global memory back to project scope
mem_deduplicate	Scan for near-duplicate memories and remove redundant entries
mem_init	Index project documentation files
mem_ingest	Refresh the index from native tool memory files

CLI reference

# Recall (runs automatically via hook)
crossmem recall                  # auto-detects project from cwd
crossmem recall -p backend-api   # explicit project
crossmem recall --format copilot # marker-wrapped for Copilot injection
crossmem recall --format vscode  # JSON for VS Code agent-mode hooks

# Search
crossmem search "JWT token rotation"
crossmem search "retry strategy" -p backend-api -n 5

# Save / Update / Delete
crossmem save "Always use middleware for credential masking" -p backend-api -s Patterns
crossmem update 42 "corrected content here"
crossmem forget 42

# Index project docs
crossmem init                        # current directory
crossmem init -p my-api --path ~/projects/api

# Hooks
crossmem install-hook                              # Claude Code (SessionStart + UserPromptSubmit)
crossmem install-hook --tool copilot               # Copilot (workspace instructions)
crossmem install-hook --tool copilot --global      # Copilot (all workspaces)
crossmem install-hook --tool copilot --if-stale    # refresh if >30 min old
crossmem install-hook --tool copilot-agent         # VS Code agent mode (.github/hooks/)
crossmem install-instructions                      # Gemini

# Internal (installed as hooks — not run manually)
crossmem prompt-search                             # mid-session recall via UserPromptSubmit

# Diagnose
crossmem doctor       # health check: binary, DB, hooks, Gemini, FTS index

# Other
crossmem ingest       # re-ingest tool memories
crossmem graph        # visualize knowledge graph in browser
crossmem stats        # database stats
crossmem setup        # one-time: Claude hook + Copilot injection + Gemini instructions + ingest

Supported tools

Tool	Memory files
Claude Code	~/.claude/projects/*/memory/*.md
Gemini CLI	~/.gemini/GEMINI.md
GitHub Copilot (macOS)	~/Library/Application Support/Code/User/globalStorage/github.copilot-chat/memory-tool/memories/*.md
GitHub Copilot (Linux)	~/.config/Code/User/globalStorage/github.copilot-chat/memory-tool/memories/*.md
GitHub Copilot (Windows)	%APPDATA%\Code\User\globalStorage\github.copilot-chat\memory-tool\memories\*.md
crossmem (via mem_save)	~/.crossmem/memories/<project>/*.md

Ingestion is pluggable — PRs welcome for new tools.

Changelog

See CHANGELOG.md for release notes.

Contributing

Found a bug? Want to add support for another AI tool? Open an issue or submit a PR.

If crossmem saves you from re-explaining your codebase to AI, consider giving it a star — it helps others find it.

License

MIT