https://github.com/amanasmuei/amem

The memory layer for AI coding tools. Local-first, semantic, works with Claude Code, Cursor, Windsurf & any MCP client.
https://github.com/amanasmuei/amem
ai claude-code cursor developer-tools embeddings mcp mcp-server memory sqlite typescript
Last synced: 3 months ago
JSON representation
The memory layer for AI coding tools. Local-first, semantic, works with Claude Code, Cursor, Windsurf & any MCP client.
Host: GitHub
URL: https://github.com/amanasmuei/amem
Owner: amanasmuei
License: mit
Created: 2026-03-20T00:07:42.000Z (3 months ago)
Default Branch: main
Last Pushed: 2026-04-03T16:36:42.000Z (3 months ago)
Last Synced: 2026-04-03T17:09:46.586Z (3 months ago)
Topics: ai, claude-code, cursor, developer-tools, embeddings, mcp, mcp-server, memory, sqlite, typescript
Language: TypeScript
Homepage: https://www.npmjs.com/package/@aman_asmuei/amem
Size: 890 KB
Stars: 1
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

README

          


  



amem




  One memory. Every AI tool.





  

   

  

   

  

   

  

   

  





  Tell your AI something once — it remembers across Claude Code, GitHub Copilot, Cursor, Windsurf, and any MCP client.


  Local-first · Semantic search · Knowledge graph · Privacy-aware · No cloud required.






  

    72% Recall@5
_{Semantic accuracy}

    0.08ms
_{Search at 10k memories}

    28 MCP tools
_{Full memory toolkit}

    357 tests
_{All passing}

  






  Quick Start •

  How It Works •

  Benchmarks •

  Tools •

  Usage Guide •

  Architecture



---

## Why amem?

Every AI tool starts from zero. Every session. Every tool.

> *"Don't use `any` in TypeScript"* — told Claude three times. Copilot still doesn't know.

>

> *"We chose PostgreSQL over MongoDB"* — explained in Cursor. Claude has no idea.

**amem** gives all your AI tools a shared, persistent memory.

```

You (in Claude Code):  "Don't use any type in TypeScript"

  amem stores this as a correction (priority 1.0)

You (switch to Copilot): starts coding

  Copilot already knows — amem feeds it the same correction

```

No cloud. No API keys. Everything stays on your machine.

---

## Quick Start

**Claude Code** (recommended)

```bash

/plugin marketplace add amanasmuei/amem

/plugin install amem

```

**GitHub Copilot CLI**

```bash

copilot plugin marketplace add amanasmuei/amem

copilot plugin install amem

```

Cursor / Windsurf / Any MCP Client

```bash

npm install -g @aman_asmuei/amem

amem-cli init      # Detects & configures all installed AI tools

amem-cli rules     # Generates extraction rules for proactive memory use

```

Or configure manually:

```json

{

  "mcpServers": {

    "amem": {

      "command": "npx",

      "args": ["-y", "@aman_asmuei/amem"]

    }

  }

}

```

**Verify it works:**

```bash

amem-cli stats     # Should show "0 memories" initially

```

Tell your AI: *"Remember: always use strict TypeScript, never use any type"*

Start a **new** session: *"What do you remember about TypeScript?"* — it recalls instantly.

---

## How It Works

amem captures knowledge in **three layers** — from fully automatic to fully manual:

| Layer | How | What it does |

|---|---|---|

| **Automatic** | Lifecycle hooks | Captures tool observations, auto-extracts corrections/decisions/patterns at session end |

| **AI-driven** | Extraction rules | Your AI proactively calls `memory_store` when you correct it, make decisions, or express preferences |

| **Manual** | Natural language | *"Remember: we use PostgreSQL"* or *"Forget the Redis memory"* |

### Memory Types

| Priority | Type | Example |

|:---:|---|---|

| **1.0** | **correction** | *"Don't mock the DB in integration tests"* |

| **0.85** | **decision** | *"Chose Postgres over Mongo for ACID"* |

| **0.7** | **pattern** | *"Prefers early returns over nesting"* |

| **0.7** | **preference** | *"Uses pnpm, not npm"* |

| **0.5** | **topology** | *"Auth module lives in src/auth/"* |

| **0.4** | **fact** | *"API launched January 2025"* |

Corrections always surface first — they are your AI's hard constraints.

### Memory Tiers

| Tier | Behavior |

|---|---|

| **Core** | Always injected at session start (~500 tokens). Your most critical corrections. |

| **Working** | Session-scoped, auto-surfaced for current task. |

| **Archival** | Default. Searchable but not auto-injected. |

### Temporal Validity

Memories aren't forever. When facts change:

- Old memories get **expired** (not deleted) — preserved for *"what was true in March?"*

- Contradictions are **auto-detected** — storing a new decision auto-expires the old one

- Query any point in time with `memory_since`

---

## Benchmarks

### Recall Accuracy

| Strategy | Recall@5 | MRR |

|---|---|---|

| FTS5 keyword only | 31.3% | 31.3% |

| **Semantic** (default) | **72.4%** | **82.5%** |

| **Multi-strategy** | **74.5%** | **76.2%** |

| + reranking (opt-in) | ~80%+ | ~85%+ |

Corpus: 34 developer memories, 16 queries, 5 graph edges.

Reproduce: `npx vitest run benchmarks/`

**Default: 72% Recall@5, 82% MRR** with local embeddings. Degrades gracefully to keyword matching (~31%) before model downloads.

### Search Latency — HNSW Vector Index

| Memories | HNSW | Brute-force | Speedup |

|---|---|---|---|

| 100 | 0.05ms | 0.10ms | 2x |

| 1,000 | 0.06ms | 0.50ms | **8x** |

| 5,000 | 0.08ms | 2.44ms | **30x** |

| 10,000 | 0.08ms | 5.35ms | **67x** |

Measured: 100 searches averaged, 384-dim embeddings, top-10 results.

**Sub-0.1ms at any scale** — effectively O(log n). HNSW is an optional dependency; brute-force is used as fallback when unavailable.

---

## Tools Reference

### Core Memory (7 tools)

| Tool | Description |

|---|---|

| `memory_store` | Store a memory with type, tags, confidence. Auto-redacts private content, auto-expires contradictions. |

| `memory_recall` | Semantic search — compact mode by default (~10x token savings). Use `memory_detail` for full content. |

| `memory_detail` | Retrieve full content by ID after compact recall. |

| `memory_context` | Load all relevant context for a topic, organized by type with token budgeting. |

| `memory_extract` | Batch-save multiple memories from conversation. |

| `memory_forget` | Delete by ID or query (with confirmation). |

| `memory_inject` | Surface corrections + decisions + graph neighbors before coding starts. |

Precision, History, Advanced, Reminders, and Maintenance tools (21 more)

### Precision & History (5 tools)

| Tool | Description |

|---|---|

| `memory_patch` | Surgical field-level edit with auto-snapshot. |

| `memory_versions` | View full edit history or restore any version. |

| `memory_search` | Exact full-text search via FTS5 with compact mode. |

| `memory_since` | Temporal query with natural language ranges (`7d`, `2w`, `1h`). |

| `memory_relate` | Build a typed knowledge graph between memories. |

### Advanced (5 tools)

| Tool | Description |

|---|---|

| `memory_multi_recall` | Multi-strategy search with compact mode: semantic + FTS5 + graph + temporal. |

| `memory_tier` | Move memories between tiers: core / working / archival. |

| `memory_expire` | Mark as no longer valid — preserved for history, excluded from recall. |

| `memory_summarize` | Store structured session summary with decisions, corrections, metrics. |

| `memory_history` | View past session summaries. |

### Reminders (4 tools)

| Tool | Description |

|---|---|

| `reminder_set` | Create reminder with optional deadline and scope. |

| `reminder_list` | List active (or all) reminders, filterable by scope. |

| `reminder_check` | Show overdue, today, and upcoming (7 days). |

| `reminder_complete` | Mark as done (supports partial ID). |

### Log & Maintenance (7 tools)

| Tool | Description |

|---|---|

| `memory_log` | Append raw conversation turns (lossless, append-only). |

| `memory_log_recall` | Search or replay log by session, keyword, or recency. |

| `memory_log_cleanup` | Prune old entries with configurable retention. |

| `memory_stats` | Counts, type breakdown, confidence distribution. |

| `memory_export` | Export as Markdown or JSON. |

| `memory_import` | Bulk import from JSON with automatic dedup. |

| `memory_consolidate` | Merge duplicates, prune stale, promote frequent, decay idle. |

---

## Usage Guide

### Storing Memories

**Natural language** (easiest)

```

"Remember: we use PostgreSQL, not MongoDB"

"Store a correction: never use console.log in production"

"Note that the auth module is in src/auth/"

```

**Explicit tool calls**

```js

memory_store({

  content: "Never use 'any' — define proper interfaces",

  type: "correction",

  tags: ["typescript"],

  confidence: 1.0

})

```

### Recalling Memories

```js

// Step 1: Compact index — ~50-100 tokens (default)

memory_recall({ query: "auth decisions", limit: 5 })

// -> a1b2c3d4 [decision] Auth service uses JWT tokens... (92%)

// -> e5f6g7h8 [correction] Never store tokens in localStorage... (100%)

// Step 2: Full details only for what you need

memory_detail({ ids: ["a1b2c3d4", "e5f6g7h8"] })

```

More search options

```js

// Multi-strategy: semantic + FTS5 + graph + temporal

memory_multi_recall({

  query: "authentication architecture",

  limit: 10,

  weights: { semantic: 0.4, fts: 0.3, graph: 0.15, temporal: 0.15 }

})

// Exact keyword search (FTS5 syntax)

memory_search({ query: "OAuth PKCE" })

memory_search({ query: '"event sourcing"' })     // phrase match

memory_search({ query: "auth* NOT legacy" })      // boolean

```

### Managing Memories

Edit, expire, promote, link

```js

// Surgical edit with auto-snapshot for rollback

memory_patch({ id: "a1b2c3d4", field: "content", value: "Updated text", reason: "clarified" })

// View edit history / restore

memory_versions({ memory_id: "a1b2c3d4" })

// Expire (preserve for history, exclude from recall)

memory_expire({ id: "a1b2c3d4", reason: "Migrated to GraphQL" })

// Promote to core tier (always loaded at session start)

memory_tier({ id: "a1b2c3d4", tier: "core" })

// Link related memories (graph builds itself, but you can add manual links)

memory_relate({ action: "relate", from_id: "abc", to_id: "xyz", relation_type: "supports" })

```

Relation types: `supports`, `contradicts`, `depends_on`, `supersedes`, `related_to`, `caused_by`, `implements` — or define your own.

### Reminders

Cross-session deadline tracking

```js

reminder_set({ content: "Review PR #42", due_at: 1743033600000, scope: "global" })

reminder_check({})

// -> [OVERDUE] Review PR #42

// -> [TODAY] Deploy auth service

// -> [upcoming] Write quarterly report

reminder_complete({ id: "a1b2c3d4" })

```

### Privacy

Automatic redaction

```js

// Private blocks stripped before storage

memory_store({

  content: "DB password is hunter2, connect to prod at db.example.com",

  type: "topology", tags: ["database"]

})

// Stored: "DB password is [REDACTED], connect to prod at db.example.com"

// API keys, tokens, passwords auto-redacted by pattern matching

// Configure patterns in ~/.amem/config.json

```

---

## Platform Compatibility

| Feature | Claude Code | GitHub Copilot CLI | Cursor / Windsurf / Other |

|---|:---:|:---:|:---:|

| One-command plugin install | Yes | Yes | -- |

| 28 MCP tools | Yes | Yes | Yes |

| AI skills | 14 | 7 | -- |

| Auto-capture hooks | Yes | Yes | -- |

| Session auto-summarize | Yes | Yes | -- |

| Auto-memory sync | Yes | -- | -- |

| CLI setup (`amem-cli init`) | Yes | Yes | Yes |

**Claude Code** has the deepest integration (plugin + hooks + auto-memory sync). **Copilot CLI** is a close second. **Other MCP clients** get the full 28-tool server via manual config.

### AI Skills

| What you say | Skill | Claude Code | Copilot CLI |

|---|---|:---:|:---:|

| *"Remember never use any type"* | `remember` | Yes | Yes |

| *"What do you remember about auth?"* | `recall` | Yes | Yes |

| *"Load context for this task"* | `context` | Yes | Yes |

| *"Show memory stats"* | `stats` | Yes | Yes |

| *"Run memory doctor"* | `doctor` | Yes | Yes |

| *"Export my memories"* | `export` | Yes | Yes |

| *"List all corrections"* | `list` | Yes | Yes |

| *"Sync my Claude memory"* | `sync` | Yes | -- |

| *"Open the memory dashboard"* | `dashboard` | Yes | -- |

| *"Install hooks"* | `hooks` | Yes | -- |

---

## Working with Claude Code Auto-Memory

amem complements Claude's built-in auto-memory — it doesn't replace it.

| | Claude auto-memory | amem |

|---|---|---|

| **Capture** | Automatic, zero config | Typed with confidence scores |

| **Storage** | Single markdown file | SQLite with search, graph, temporal |

| **Recall** | Entire file loaded every session | Only relevant memories surfaced |

| **History** | Overwritten on update | Versioned, temporal validity |

| **Search** | None | Semantic + FTS5 + graph + reranking |

**Recommended:** Keep both enabled. Run `amem-cli sync` to import Claude's memories into amem for unified, structured access.

Sync details

```bash

amem-cli sync              # Import all projects

amem-cli sync --dry-run    # Preview what would be imported

amem-cli sync --project myapp  # Import specific project

```

| Claude type | amem type | Confidence |

|---|---|---|

| `feedback` | `correction` | 1.0 |

| `project` | `decision` | 0.85 |

| `user` | `preference` | 0.8 |

| `reference` | `topology` | 0.7 |

---

## Dashboard

```bash

amem-cli dashboard              # Opens at localhost:3333

amem-cli dashboard --port=8080  # Custom port

```

Memory list with search and filters, inline actions (promote, demote, expire), interactive knowledge graph, confidence charts, session timeline, reminders, and conversation log.

---

## CLI Reference

```bash

# Setup

amem-cli init                          # Auto-configure AI tools

amem-cli rules                         # Generate extraction rules

amem-cli hooks                         # Install automatic capture hooks

amem-cli hooks --uninstall             # Remove hooks

amem-cli sync                          # Import Claude auto-memory

amem-cli doctor                        # Health diagnostics

amem-cli repair                        # Repair corrupted database from backups

# Dashboard

amem-cli dashboard                     # Web dashboard (localhost:3333)

# Memory operations

amem-cli recall "authentication"       # Semantic search

amem-cli stats                         # Statistics

amem-cli list --type correction        # List by type

amem-cli export --file memories.md     # Export to file

amem-cli forget abc12345               # Delete by short ID

amem-cli reset --confirm               # Wipe all data

```

---

## Architecture

```

                        Your AI Tool

           Claude Code / Copilot CLI / any MCP client

                    |                |

                    | MCP (stdio)    | Lifecycle Hooks

                    v                v

          +---------------------------------+

          |        amem MCP Server          |

          |                                 |

          |  28 Tools . 7 Resources . 2 Prompts

          |                                 |

          |  Multi-Strategy Retrieval       |

          |  [HNSW] + [FTS5] + [Graph] + [Temporal]

          |       + query expansion         |

          |       + cross-encoder (opt-in)  |

          |                                 |

          |  +---------------------------+  |

          |  | SQLite + WAL + FTS5       |  |

          |  | ~/.amem/memory.db         |  |

          |  |                           |  |

          |  | memories      (tiered)    |  |

          |  | conversation_log (raw)    |  |

          |  | memory_versions (history) |  |

          |  | memory_relations (graph)  |  |

          |  | session_summaries         |  |

          |  | reminders                 |  |

          |  +---------------------------+  |

          |                                 |

          |  Embeddings: bge-small-en-v1.5  |

          |  Config: ~/.amem/config.json    |

          +---------------------------------+

```

### Ranking Formula

```

score = relevance x 0.45 + recency x 0.2 + confidence x 0.2 + importance x 0.15

```

| Factor | How it works |

|---|---|

| **Relevance** | Cosine similarity via HNSW index; query-expanded keyword fallback |

| **Recency** | Exponential decay (`0.995^hours`) |

| **Confidence** | Reinforced by repeated confirmation (0-1) |

| **Importance** | Type-based: corrections `1.0` ... facts `0.4` |

Additive scoring ensures no single low factor kills the ranking.

---

## Configuration

Environment variables

| Variable | Default | Description |

|---|---|---|

| `AMEM_DIR` | `~/.amem` | Storage directory |

| `AMEM_DB` | `~/.amem/memory.db` | Database path |

| `AMEM_PROJECT` | *(auto from git)* | Project scope override |

Config file (~/.amem/config.json)

Created automatically with defaults:

```json

{

  "retrieval": {

    "semanticWeight": 0.4,

    "ftsWeight": 0.3,

    "graphWeight": 0.15,

    "temporalWeight": 0.15,

    "rerankerEnabled": false

  },

  "privacy": {

    "enablePrivateTags": true,

    "redactPatterns": ["..."]

  },

  "tiers": {

    "coreMaxTokens": 500,

    "workingMaxTokens": 2000

  },

  "hooks": {

    "enabled": true,

    "captureToolUse": true,

    "captureSessionEnd": true

  }

}

```

Version history

### v0.18.0 — Progressive Disclosure & Scale

HNSW vector index (67x faster at 10k), compact mode default on recall/search, DB repair CLI, concurrent access safety, heuristic conversation extractor, session-end auto-extraction.

### v0.13.0 — World-Class Recall

bge-small-en-v1.5 embeddings, additive scoring, query expansion, auto-relate knowledge graph, graph-aware injection, amem doctor, CI benchmarks.

### v0.9.x — Temporal Intelligence

Temporal validity, auto-expire contradictions, multi-strategy retrieval, cross-encoder reranking, memory tiers, privacy tags, lifecycle hooks, session summaries, dashboard, config system.

### v0.7.0 — v0.8.0

Import/export, confidence decay, embedding cache, multi-process safety, auto-configure CLI, dashboard.

### v0.1.0 — v0.5.x

Core store/recall, local embeddings, SQLite + WAL, consolidation, project scoping, reminders, conversation log, knowledge graph, FTS5, progressive disclosure.

---

## Tech Stack

| Layer | Technology |

|---|---|

| Protocol | MCP SDK ^1.25 |

| Language | TypeScript 5.6+, strict mode |

| Database | SQLite + WAL + FTS5 |

| Embeddings | HuggingFace bge-small-en-v1.5 (local, 80MB) + HNSW vector index |

| Reranking | ms-marco-MiniLM-L-6-v2 (optional, local) |

| Validation | Zod 3.25+ with `.strict()` schemas |

| Testing | Vitest — 357 tests across 28 suites + recall benchmarks |

| CI/CD | GitHub Actions, npm publish on release |

---

## Contributing

```bash

git clone https://github.com/amanasmuei/amem.git

cd amem && npm install

npm run build   # zero TS errors

npm test        # 357 tests pass

```

PRs must pass CI before merge. See [Issues](https://github.com/amanasmuei/amem/issues) for open tasks.

---



  Built by Aman Asmuei





  GitHub ·

  npm ·

  Issues





  _{MIT License}
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/amanasmuei/amem

Awesome Lists containing this project

README

amem
