Metadata-Version: 2.4
Name: crossmem
Version: 1.9.0
Summary: Cross-project memory for AI coding agents
Keywords: ai,memory,mcp,developer-tools,cross-project
Author: Md Niajul Hasan
Author-email: Md Niajul Hasan <niajul1992@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: click>=8.0
Requires-Dist: mcp>=1.27.0
Requires-Dist: pytest>=8.0 ; extra == 'dev'
Requires-Dist: ruff>=0.4 ; extra == 'dev'
Requires-Dist: fastembed>=0.3.0 ; extra == 'embeddings'
Requires-Dist: sqlite-vec>=0.1.0 ; extra == 'embeddings'
Requires-Python: >=3.12
Provides-Extra: dev
Provides-Extra: embeddings
Description-Content-Type: text/markdown

<p align="center">
  <img src="visuals/logo.svg" alt="crossmem" width="360"/>
</p>

<p align="center">
  <a href="https://pypi.org/project/crossmem/"><img src="https://img.shields.io/pypi/v/crossmem" alt="PyPI"></a>
  <a href="https://pypistats.org/packages/crossmem"><img src="https://img.shields.io/pypi/dm/crossmem" alt="Downloads"></a>
  <a href="https://pypi.org/project/crossmem/"><img src="https://img.shields.io/pypi/pyversions/crossmem" alt="Python"></a>
  <a href="https://github.com/Crack525/crossmem/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/crossmem" alt="License"></a>
</p>

**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.

![Before and after crossmem](visuals/problem-solution.png)

## Quick start

```bash
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.

![crossmem demo](demo/demo.gif)

## 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](https://github.com/Crack525/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:

<details>
<summary><strong>Claude Code</strong> (<code>~/.mcp.json</code>)</summary>

```json
{
  "mcpServers": {
    "crossmem": {
      "command": "crossmem-server"
    }
  }
}
```
</details>

<details>
<summary><strong>GitHub Copilot</strong> (<code>.vscode/mcp.json</code>)</summary>

```json
{
  "servers": {
    "crossmem": {
      "command": "uvx",
      "args": ["--from", "crossmem", "crossmem-server"]
    }
  }
}
```
</details>

<details>
<summary><strong>Gemini CLI</strong> (<code>~/.gemini/settings.json</code>)</summary>

```json
{
  "mcpServers": {
    "crossmem": {
      "command": "crossmem-server"
    }
  }
}
```
</details>

> 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 |

<details>
<summary><strong>CLI reference</strong></summary>

```bash
# 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
```
</details>

## 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](CHANGELOG.md) for release notes.

## Contributing

Found a bug? Want to add support for another AI tool? [Open an issue](https://github.com/Crack525/crossmem/issues) 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
