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 · Self-evolving · Privacy-aware · No cloud required.
| 94.8% R@5 LongMemEval Oracle, 500q |
0.08ms Search at 10k memories |
29 MCP tools Full memory toolkit |
Powered by amem-core |
Quick Start • How It Works • Benchmarks • Tools • Usage Guide • Architecture
Every AI tool starts from zero. Every session. Every tool.
"Don't use
anyin 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.
amem is the MCP server. The actual memory engine — embeddings, recall, knowledge graph, contradiction detection, reflection — lives in a separate package: @aman_asmuei/amem-core.
Claude Code / Copilot / Cursor / any MCP client
│
│ MCP (stdio)
▼
┌─────────────────────────────────┐
│ @aman_asmuei/amem (this pkg) │
│ 29 MCP tools, CLI, hooks │
└────────────────┬────────────────┘
│ imports
▼
┌─────────────────────────────────┐
│ @aman_asmuei/amem-core │
│ embeddings · HNSW · recall │
│ knowledge graph · reflection │
│ 91.0% R@5 on LongMemEval │
└────────────────┬────────────────┘
│
▼
┌────────────────────┐
│ SQLite (one file) │
│ ~/.amem/memory.db │
└────────────────────┘
| Package | Role | Install | Use case |
|---|---|---|---|
@aman_asmuei/amem (this) |
MCP server + CLI + hooks | npm install -g @aman_asmuei/amem |
Plug into Claude Code, Copilot, Cursor, any MCP client |
@aman_asmuei/amem-core |
Pure TypeScript library, zero MCP deps | npm install @aman_asmuei/amem-core |
Embed memory directly in your own Node app |
Why the split? The same engine powers amem (this MCP server), aman-agent (CLI), aman-tg (Telegram bot), and any other Node app you want to give memory to. All retrieval-quality improvements ship via amem-core. All MCP-tool changes ship via amem. They version independently.
The 94.8% R@5 headline is the engine quality from
amem-core— exactly what you get whether you call it through this MCP server or import the library directly. The MCP wrapper does not change retrieval quality.
|
Claude Code (recommended) /plugin marketplace add amanasmuei/amem
/plugin install amem |
GitHub Copilot CLI copilot plugin marketplace add amanasmuei/amem
copilot plugin install amem |
Cursor / Windsurf / Any MCP Client
npm install -g @aman_asmuei/amem
amem-cli init # Detects & configures all installed AI tools
amem-cli rules # Generates extraction rules for proactive memory useOr configure manually:
{
"mcpServers": {
"amem": {
"command": "npx",
"args": ["-y", "@aman_asmuei/amem"]
}
}
}Verify it works:
amem-cli stats # Should show "0 memories" initiallyTell your AI: "Remember: always use strict TypeScript, never use any type"
Start a new session: "What do you remember about TypeScript?" — it recalls instantly.
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" |
| 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.
| 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. |
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
Your memory doesn't just store — it learns from its own structure. Call memory_reflect to trigger the reflection engine:
memory_reflect → Analyzes your entire memory graph
│
├─ Clusters related memories (HNSW neighbor graph)
├─ Detects contradictions (negation pairs, numerical, low-overlap)
├─ Identifies synthesis candidates
├─ Surfaces knowledge gaps (topics with sparse recall)
└─ Returns a structured report with suggested actions
The evolution loop:
- Reflect —
memory_reflectclusters your memories and finds patterns - Synthesize — AI merges related clusters into higher-order principles via
memory_store - Link —
memory_relateconnects syntheses to source memories (tracked via synthesis lineage) - Repeat — each cycle, the graph becomes more coherent and abstract
The system auto-nudges when reflection is due (>7 days or >50 new memories since last run).
What the reflection report looks like
# Memory Reflection Report
Analyzed 127 memories in 12ms
Health Score: 68/100
## Stats
- Clusters: 8 (avg size: 4.2)
- Clustered: 34 | Orphans: 93
- Contradictions: 2
- Synthesis candidates: 3
- Knowledge gaps: 4
## Contradictions Found
⚠ Opposing language detected (23d apart, 87% similar)
A: a1b2c3d4 "Always use semicolons in JavaScript..."
B: e5f6g7h8 "Never use semicolons in JavaScript..."
→ Expire older memory a1b2c3d4 — newer supersedes it
## Synthesis Candidates
### cluster-0 (4 patterns)
"These 4 related memories form a cluster about 'typescript, types':
[patterns]:
- 'Always use strict TypeScript types'
- 'Prefer strict null checks'
- 'Use unknown instead of any'
- 'Enable strictNullChecks in tsconfig'
Synthesize into a higher-order principle..."
## Knowledge Gaps
- "kubernetes deployment" — asked 3x, avg 25% confidence
- "database migration strategy" — asked 2x, avg 0% confidence
|
Corpus: 34 developer memories, 16 queries, 5 graph edges. Reproduce: Default: 72% Recall@5, 82% MRR with local embeddings. Degrades gracefully to keyword matching (~31%) before model downloads. |
|
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. |
| 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 (22 more)
| 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. |
| 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. |
memory_reflect |
Self-evolving reflection engine — clusters memories, detects contradictions, identifies synthesis candidates, surfaces knowledge gaps. |
| 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). |
| 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. |
|
Natural language (easiest) |
Explicit tool calls memory_store({
content: "Never use 'any' — define proper interfaces",
type: "correction",
tags: ["typescript"],
confidence: 1.0
}) |
// 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
// 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" }) // booleanEdit, expire, promote, link
// 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.
Cross-session deadline tracking
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" })Automatic redaction
// Private blocks stripped before storage
memory_store({
content: "DB password is <private>hunter2</private>, 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| Feature | Claude Code | GitHub Copilot CLI | Cursor / Windsurf / Other |
|---|---|---|---|
| One-command plugin install | Yes | Yes | -- |
| 29 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 29-tool server via manual config.
| 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 | -- |
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.
Claude → amem sync
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 |
amem → Copilot sync
Export amem memories to .github/copilot-instructions.md so Copilot reads them as persistent context:
amem-cli sync --to copilot # Export to current project
amem-cli sync --to copilot --dry-run # Preview without writing
amem-cli sync --to copilot --project /path/to/repoThis generates structured markdown grouped by priority:
- Corrections (MUST follow) — hard constraints
- Decisions — architectural choices
- Preferences — user preferences
- Patterns — coding conventions
- Context — topology + facts
The amem section is wrapped in <!-- amem:start/end --> markers — existing non-amem content in the file is preserved.
Cross-tool sync: Decisions made in Claude sessions automatically inform Copilot:
Claude Code → amem sync → amem DB → amem sync --to copilot → copilot-instructions.md
amem-cli dashboard # Opens at localhost:3333
amem-cli dashboard --port=8080 # Custom portMemory list with search and filters (type, tier, source), inline actions (promote, demote, expire), interactive knowledge graph, confidence charts, session timeline, reminders, conversation log, and Copilot Instructions Preview panel with copy-to-clipboard.
# Setup
amem-cli init # Auto-configure AI tools
amem-cli rules # Generate extraction rules
amem-cli hooks # Install hooks for Claude Code
amem-cli hooks --target copilot # Install hooks for GitHub Copilot CLI
amem-cli hooks --uninstall # Remove hooks
amem-cli sync # Import Claude auto-memory → amem
amem-cli sync --to copilot # Export amem → copilot-instructions.md
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 Your AI Tool
Claude Code / Copilot CLI / any MCP client
│ │
│ MCP (stdio) │ Lifecycle Hooks
▼ ▼
┌─────────────────────────────────┐
│ @aman_asmuei/amem │ ← this package
│ │
│ 29 Tools · 7 Resources · 2 Prompts
│ Slash commands · CLI · Hooks │
│ Config: ~/.amem/config.json │
└────────────────┬────────────────┘
│ imports
▼
┌─────────────────────────────────┐
│ @aman_asmuei/amem-core │ ← the engine
│ │
│ Multi-Strategy Retrieval │
│ [HNSW] + [FTS5] + [Graph] + [Temporal]
│ + query expansion │
│ + cross-encoder (opt-in) │
│ │
│ Self-Evolving Reflection │
│ [Clustering] + [Contradictions]│
│ + [Synthesis] + [Gap Detection]│
│ │
│ Embeddings: bge-small-en-v1.5 │
│ 94.8% R@5 on LongMemEval │
└────────────────┬────────────────┘
│
▼
┌─────────────────────────────────┐
│ SQLite + WAL + FTS5 │
│ ~/.amem/memory.db │
│ │
│ memories (tiered) │
│ conversation_log (raw) │
│ memory_versions (history) │
│ memory_relations (graph) │
│ synthesis_lineage │
│ knowledge_gaps │
│ session_summaries │
│ reminders │
└─────────────────────────────────┘
The amem MCP server is a thin wrapper around amem-core. The retrieval engine, embeddings, knowledge graph, reflection — all live in amem-core and version independently. Bug in MCP wiring? Republish amem. Recall improvement? Republish amem-core. No coupling.
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.
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:
{
"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
Reflection engine with HNSW-based clustering, 3-layer contradiction detection (negation + numerical + low-overlap), synthesis candidates with lineage tracking, knowledge gap detection, utility scoring, auto-trigger nudge in memory_inject. New DB tables: synthesis_lineage, knowledge_gaps, reflection_meta. Migration v5.
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.
bge-small-en-v1.5 embeddings, additive scoring, query expansion, auto-relate knowledge graph, graph-aware injection, amem doctor, CI benchmarks.
Temporal validity, auto-expire contradictions, multi-strategy retrieval, cross-encoder reranking, memory tiers, privacy tags, lifecycle hooks, session summaries, dashboard, config system.
Import/export, confidence decay, embedding cache, multi-process safety, auto-configure CLI, dashboard.
Core store/recall, local embeddings, SQLite + WAL, consolidation, project scoping, reminders, conversation log, knowledge graph, FTS5, progressive disclosure.
| 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 — 388 tests across 29 suites + recall benchmarks |
| CI/CD | GitHub Actions, npm publish on release |
git clone https://github.com/amanasmuei/amem.git
cd amem && npm install
npm run build # zero TS errors
npm test # 388 tests passPRs must pass CI before merge. See Issues for open tasks.
Built with ❤️ in 🇲🇾 Malaysia by Aman Asmuei
MIT License