# apex-memory

[![CI](https://github.com/JJerryChoi/apex-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/JJerryChoi/apex-memory/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/apex-memory.svg)](https://www.npmjs.com/package/apex-memory)
[![npm downloads](https://img.shields.io/npm/dm/apex-memory.svg)](https://www.npmjs.com/package/apex-memory)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Persistent memory for AI coding agents.**

Give your AI coding agent memory that survives across sessions. apex-memory is an [MCP](https://modelcontextprotocol.io) server that lets agents save decisions, patterns, bugs, and context — then recall them exactly when needed.

- **One install, works everywhere** — MCP-native, works with Claude Code, Cursor, Windsurf, and any MCP-compatible editor
- **Ultra-lightweight** — 26.6 kB package, starts in milliseconds, no ML models or vector databases
- **Zero infrastructure** — local SQLite database, no servers, no accounts
- **Built for coding agents** — categories like `decision`, `architecture`, `bug`, `pattern` designed for real development workflows
- **Smart memory management** — importance scoring (1-5), access tracking, and auto-decay keep your memory store relevant
- **Full-text search** — find any memory instantly with FTS5-powered search
- **Knowledge graph** — link memories with directional relationships (related, depends_on, supersedes, contradicts, extends)
- **Dedup detection** — automatic duplicate warnings on save, Jaccard similarity scanning, and one-click merge
- **Cloud sync** — sync memories across machines with the Pro tier

## Quick Start

### Claude Code

```bash
claude mcp add apex-memory -- npx apex-memory
```

That's it. Your agent now has persistent memory.

### Cursor

Add to your MCP settings (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "apex-memory": {
      "command": "npx",
      "args": ["apex-memory"]
    }
  }
}
```

See the [Cursor setup guide](docs/guides/cursor.md) for full details and troubleshooting.

### Windsurf

Open `~/.codeium/windsurf/mcp_config.json` (via `Cmd+Shift+P` → "Windsurf: Open MCP Config") and add:

```json
{
  "mcpServers": {
    "apex-memory": {
      "command": "npx",
      "args": ["apex-memory"]
    }
  }
}
```

See the [Windsurf setup guide](docs/guides/windsurf.md) for full details and troubleshooting.

### VS Code + GitHub Copilot

In your project root, create `.vscode/mcp.json`:

```json
{
  "servers": {
    "apex-memory": {
      "command": "npx",
      "args": ["apex-memory"]
    }
  }
}
```

See the [VS Code setup guide](docs/guides/vscode.md) for full details and troubleshooting.

### Cline

Open the MCP Servers panel in Cline's sidebar → **Edit MCP Settings**, then add:

```json
{
  "mcpServers": {
    "apex-memory": {
      "command": "npx",
      "args": ["apex-memory"],
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

See the [Cline setup guide](docs/guides/cline.md) for full details and troubleshooting.

### Other MCP Clients

apex-memory works with any MCP-compatible client. Point it at:

```bash
npx apex-memory
```

The server communicates over stdio using the standard MCP protocol. See the [generic MCP setup guide](docs/guides/generic-mcp.md) for examples with VS Code, Continue.dev, and custom clients.

### New to apex-memory?

Follow the **[Getting Started tutorial](docs/guides/getting-started.md)** — install, configure, and save your first memory in under 2 minutes. Includes a CLAUDE.md integration snippet and copy-paste editor configs in [`docs/editors/`](docs/editors/).

## Tools

apex-memory gives your agent 30 tools:

| Tool | Description |
|------|-------------|
| `save_memory` | Save knowledge, decisions, patterns, or context with categories, tags, and importance scoring (1–5). Warns about potential duplicates automatically. |
| `search_memories` | Full-text search across all memories (supports AND, OR, NOT, phrases). Falls back to fuzzy substring matching when FTS5 returns no results. |
| `recall` | Retrieve recent memories filtered by project, category, or tags. Sort by `recent` or `relevant` (weighted by importance + recency + access frequency). |
| `update_memory` | Update an existing memory's content, category, tags, or importance in place |
| `delete_memory` | Remove a specific memory by ID |
| `decay_memories` | Archive old low-importance memories that were never accessed — keeps the store clean |
| `start_session` | Begin a coding session tied to a project |
| `end_session` | End a session with a summary of what was accomplished |
| `list_sessions` | View past coding sessions |
| `memory_stats` | Get detailed statistics: totals, category breakdown, importance distribution, most accessed memories |
| `export_memories` | Export all memories and sessions as JSON — useful for backup, migration, or sharing context across machines |
| `import_memories` | Import memories and sessions from a JSON export — restore backups or merge context from another machine |
| `export_to_claudemd` | Export key memories as a CLAUDE.md-ready context block — inject project memory directly into your agent's instructions |
| `link_memories` | Create directional links between memories (related, depends_on, supersedes, contradicts, extends) — build a knowledge graph |
| `get_linked_memories` | Query the knowledge graph — find all memories connected to a given memory |
| `find_duplicates` | Detect similar existing memories using FTS5 search |
| `find_duplicate_groups` | Scan for duplicate clusters using Jaccard similarity — returns groups of similar memories |
| `merge_memories` | Consolidate duplicates: keeps primary content, max importance, union tags, re-points links, soft-deletes merged |
| `apex_memory_sync` | Manually trigger a cloud sync — push local changes and pull remote (Pro) |
| `apex_memory_login` | Register this machine with apex-memory cloud and get a Pro upgrade link |
| `apex_memory_status` | Show cloud sync status: workspace ID, subscription tier, last sync time |
| `apex_memory_auto_capture` | Automatically capture session context (decisions, files, errors, solutions) at session end |
| `memory_context` | Get full memory context in one call — combines relevant memories, linked memories (knowledge graph), and recent sessions |
| `batch_save_memories` | Save multiple memories in a single transaction — much faster than calling save_memory repeatedly |
| `memory_timeline` | Chronological activity feed of memory events: creations, updates, sessions, and links |
| `session_summary` | Review all memories captured in a session — use at session start to restore prior context |
| `list_tags` | List all tags across memories with counts — discover how memories are organized and find tags to filter by |
| `memory_graph` | Get the knowledge graph as nodes and edges — visualize how memories relate to each other |
| `memory_health` | Diagnose store health — stale memories, orphaned links, untagged items, cleanup candidates |
| `cleanup_orphaned_links` | Remove links pointing to deleted memories — keep the knowledge graph clean |

## How It Works

When your agent encounters something worth remembering — an architectural decision, a tricky bug fix, a user preference — it calls `save_memory`:

```
save_memory({
  content: "User prefers functional components over class components in React",
  category: "preference",
  tags: ["react", "components"],
  project: "frontend-app"
})
```

Next session, the agent recalls context before starting work:

```
recall({ project: "frontend-app" })
```

Or searches for something specific:

```
search_memories({ query: "authentication AND JWT" })
```

### Categories

Organize memories by what they represent:

| Category | Use for |
|----------|---------|
| `decision` | Architectural and design decisions |
| `pattern` | Code patterns and conventions |
| `bug` | Bugs encountered and their fixes |
| `architecture` | System design and structure |
| `preference` | User and team preferences |
| `learning` | Lessons learned |
| `context` | Project context and background |
| `general` | Everything else |

### Sessions

Track coding sessions to group related memories:

```
start_session({ project: "api-server" })
// ... agent works, saves memories with the session_id ...
end_session({ session_id: "...", summary: "Refactored auth middleware to use JWT" })
```

## Memory Linking

Connect related memories into a knowledge graph:

```
link_memories({
  source_id: "decision-about-jwt",
  target_id: "bug-with-token-expiry",
  link_type: "related"
})
```

Five link types: `related`, `depends_on`, `supersedes`, `contradicts`, `extends`. Query connections with `get_linked_memories`, scan for duplicates with `find_duplicate_groups`, and merge them with `merge_memories`.

## Cloud Sync (Pro)

Sync memories across machines with a Pro subscription ($9/workspace/month).

**1. Register and get a Pro upgrade link:**

```
apex_memory_login({
  server_url: "https://apex-memory-sync.your-account.workers.dev",
  email: "you@example.com"
})
```

This registers your workspace, stores an API key locally, and returns a checkout URL to activate Pro.

**2. Check your sync status:**

```
apex_memory_status()
```

Shows workspace ID, subscription tier, and last sync timestamp.

**3. Sync manually at any time:**

```
apex_memory_sync()
```

Pushes local changes to the cloud and pulls remote changes. Memories are merged across machines.

> Auto-sync also runs on agent startup when Pro is active — no manual trigger needed.

## Auto-Capture

Auto-capture saves session context automatically at the end of every coding session — no manual `save_memory` calls needed.

```
apex_memory_auto_capture({
  project: "api-server",
  summary: "Refactored auth middleware to use JWT refresh tokens",
  session_id: "...",
  decisions: ["Use RS256 signing for cross-service token validation"],
  files_worked_on: ["src/auth/middleware.ts", "src/auth/tokens.ts"],
  errors_encountered: ["JWT expired during refresh cycle"],
  solutions_found: ["Added 30s clock skew tolerance to token validation"]
})
```

At the start of your next session, use `session_summary` to recall what was captured:

```
session_summary({ session_id: "..." })
```

Auto-capture is enabled by default. To disable, set `auto_capture.enabled = false` in `~/.apex-memory/config.json`.

## Storage

All data is stored locally in `~/.apex-memory/memory.db` — a SQLite database with WAL mode and FTS5 full-text search. No data leaves your machine.

## Pricing

**Free and open source.** The core MCP server is MIT-licensed and fully functional — local storage, unlimited memories, unlimited sessions, no restrictions.

**Pro tier — $9/workspace/month.** Everything in Free, plus:

- **Sync across machines in under 1 second** — memories are always current wherever you work
- **Automatic cloud backup** — your memory store is continuously backed up, zero maintenance
- **Access from any editor on any machine** — Claude Code, Cursor, Windsurf, all sharing one memory store

[Pricing details](docs/pricing.md) · [Upgrade guide](docs/guides/pro-upgrade.md)

**Support the project.** If apex-memory is useful to you, consider [sponsoring on GitHub](https://github.com/sponsors/JJerryChoi).

## Why apex-memory?

### vs. MCP memory servers

| | apex-memory | shieldcortex | cortex-mcp | kiro-memory | claude-recall |
|---|---|---|---|---|---|
| **Package size** | **26.6 kB** | 75.9 MB | 1.1 MB | 3.6 MB | 862 kB |
| **Install time** | Instant | Slow (ML deps) | Fast | Fast | Fast |
| **Cloud sync** | **Yes (Pro)** | No | No | No | No |
| **Knowledge graph** | **Built-in** | No | No | No | No |
| **Dedup detection & merge** | **Built-in** | No | No | No | No |
| **Importance scoring** | Built-in | No | No | No | No |
| **Auto-decay** | Built-in | Yes | No | No | No |
| **Session tracking** | Built-in | No | No | No | No |
| **Works with any MCP client** | Yes | Yes | Yes | Yes | Claude-only |
| **License** | MIT | MIT | MIT | AGPL-3.0 | ISC |
| **Dependencies** | 3 | 8 (incl. HuggingFace) | 3 | 16 | 5 |

**apex-memory is 32x smaller than the next smallest competitor** and starts in milliseconds. No ML models, no vector databases, no bloat — just fast, reliable memory backed by SQLite FTS5.

### vs. general-purpose memory

| | apex-memory | Mem0 | Letta | OneContext |
|---|---|---|---|---|
| **Built for coding agents** | Yes | General purpose | General purpose | General purpose |
| **MCP-native** | Yes | No | No | No |
| **Zero infrastructure** | Yes (SQLite) | Requires server | Requires server | Cloud-only |
| **Open source** | MIT | Partial | Yes | No |

apex-memory is purpose-built for the coding agent workflow. It's not a general-purpose memory layer — it's the memory system your AI coding agent should have had from day one.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

[MIT](LICENSE)