{"id":47784030,"url":"https://github.com/amanasmuei/amem","last_synced_at":"2026-04-08T15:00:41.369Z","repository":{"id":345630852,"uuid":"1186740684","full_name":"amanasmuei/amem","owner":"amanasmuei","description":"The memory layer for AI coding tools. Local-first, semantic, works with Claude Code, Cursor, Windsurf \u0026 any MCP client.","archived":false,"fork":false,"pushed_at":"2026-04-03T16:36:42.000Z","size":911,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T17:09:46.586Z","etag":null,"topics":["ai","claude-code","cursor","developer-tools","embeddings","mcp","mcp-server","memory","sqlite","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@aman_asmuei/amem","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amanasmuei.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-20T00:07:42.000Z","updated_at":"2026-04-03T16:36:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/amanasmuei/amem","commit_stats":null,"previous_names":["amanasmuei/amem"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/amanasmuei/amem","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amanasmuei%2Famem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amanasmuei%2Famem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amanasmuei%2Famem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amanasmuei%2Famem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amanasmuei","download_url":"https://codeload.github.com/amanasmuei/amem/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amanasmuei%2Famem/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31407563,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude-code","cursor","developer-tools","embeddings","mcp","mcp-server","memory","sqlite","typescript"],"created_at":"2026-04-03T14:05:38.084Z","updated_at":"2026-04-08T15:00:41.328Z","avatar_url":"https://github.com/amanasmuei.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.png\" alt=\"amem\" width=\"160\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eamem\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eOne memory. Every AI tool.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@aman_asmuei/amem\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@aman_asmuei/amem?style=for-the-badge\u0026logo=npm\u0026logoColor=white\u0026color=cb3837\" alt=\"npm version\" /\u003e\u003c/a\u003e\n  \u0026nbsp;\n  \u003ca href=\"https://github.com/amanasmuei/amem/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/amanasmuei/amem/ci.yml?style=for-the-badge\u0026logo=github\u0026label=CI\" alt=\"CI status\" /\u003e\u003c/a\u003e\n  \u0026nbsp;\n  \u003ca href=\"https://github.com/amanasmuei/amem/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue?style=for-the-badge\" alt=\"MIT License\" /\u003e\u003c/a\u003e\n  \u0026nbsp;\n  \u003cimg src=\"https://img.shields.io/badge/MCP-compatible-8A2BE2?style=for-the-badge\" alt=\"MCP compatible\" /\u003e\n  \u0026nbsp;\n  \u003cimg src=\"https://img.shields.io/badge/node-%E2%89%A518-brightgreen?style=for-the-badge\u0026logo=node.js\u0026logoColor=white\" alt=\"Node.js 18+\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Tell your AI something once — it remembers across Claude Code, GitHub Copilot, Cursor, Windsurf, and any MCP client.\u003cbr/\u003e\n  Local-first \u0026middot; Semantic search \u0026middot; Knowledge graph \u0026middot; Privacy-aware \u0026middot; No cloud required.\n\u003c/p\u003e\n\n\u003cbr/\u003e\n\n\u003ctable align=\"center\"\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cstrong\u003e72% Recall@5\u003c/strong\u003e\u003cbr/\u003e\u003csub\u003eSemantic accuracy\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cstrong\u003e0.08ms\u003c/strong\u003e\u003cbr/\u003e\u003csub\u003eSearch at 10k memories\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cstrong\u003e28 MCP tools\u003c/strong\u003e\u003cbr/\u003e\u003csub\u003eFull memory toolkit\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cstrong\u003e357 tests\u003c/strong\u003e\u003cbr/\u003e\u003csub\u003eAll passing\u003c/sub\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cbr/\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#-quick-start\"\u003eQuick Start\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#-how-it-works\"\u003eHow It Works\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#-benchmarks\"\u003eBenchmarks\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#-tools-reference\"\u003eTools\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#-usage-guide\"\u003eUsage Guide\u003c/a\u003e \u0026bull;\n  \u003ca href=\"#-architecture\"\u003eArchitecture\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Why amem?\n\nEvery AI tool starts from zero. Every session. Every tool.\n\n\u003e *\"Don't use `any` in TypeScript\"* — told Claude three times. Copilot still doesn't know.\n\u003e\n\u003e *\"We chose PostgreSQL over MongoDB\"* — explained in Cursor. Claude has no idea.\n\n**amem** gives all your AI tools a shared, persistent memory.\n\n```\nYou (in Claude Code):  \"Don't use any type in TypeScript\"\n  amem stores this as a correction (priority 1.0)\n\nYou (switch to Copilot): starts coding\n  Copilot already knows — amem feeds it the same correction\n```\n\nNo cloud. No API keys. Everything stays on your machine.\n\n---\n\n## Quick Start\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n**Claude Code** (recommended)\n\n```bash\n/plugin marketplace add amanasmuei/amem\n/plugin install amem\n```\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n**GitHub Copilot CLI**\n\n```bash\ncopilot plugin marketplace add amanasmuei/amem\ncopilot plugin install amem\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCursor / Windsurf / Any MCP Client\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\nnpm install -g @aman_asmuei/amem\namem-cli init      # Detects \u0026 configures all installed AI tools\namem-cli rules     # Generates extraction rules for proactive memory use\n```\n\nOr configure manually:\n\n```json\n{\n  \"mcpServers\": {\n    \"amem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aman_asmuei/amem\"]\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n**Verify it works:**\n\n```bash\namem-cli stats     # Should show \"0 memories\" initially\n```\n\nTell your AI: *\"Remember: always use strict TypeScript, never use any type\"*\n\nStart a **new** session: *\"What do you remember about TypeScript?\"* — it recalls instantly.\n\n---\n\n## How It Works\n\namem captures knowledge in **three layers** — from fully automatic to fully manual:\n\n| Layer | How | What it does |\n|---|---|---|\n| **Automatic** | Lifecycle hooks | Captures tool observations, auto-extracts corrections/decisions/patterns at session end |\n| **AI-driven** | Extraction rules | Your AI proactively calls `memory_store` when you correct it, make decisions, or express preferences |\n| **Manual** | Natural language | *\"Remember: we use PostgreSQL\"* or *\"Forget the Redis memory\"* |\n\n### Memory Types\n\n| Priority | Type | Example |\n|:---:|---|---|\n| **1.0** | **correction** | *\"Don't mock the DB in integration tests\"* |\n| **0.85** | **decision** | *\"Chose Postgres over Mongo for ACID\"* |\n| **0.7** | **pattern** | *\"Prefers early returns over nesting\"* |\n| **0.7** | **preference** | *\"Uses pnpm, not npm\"* |\n| **0.5** | **topology** | *\"Auth module lives in src/auth/\"* |\n| **0.4** | **fact** | *\"API launched January 2025\"* |\n\nCorrections always surface first — they are your AI's hard constraints.\n\n### Memory Tiers\n\n| Tier | Behavior |\n|---|---|\n| **Core** | Always injected at session start (~500 tokens). Your most critical corrections. |\n| **Working** | Session-scoped, auto-surfaced for current task. |\n| **Archival** | Default. Searchable but not auto-injected. |\n\n### Temporal Validity\n\nMemories aren't forever. When facts change:\n- Old memories get **expired** (not deleted) — preserved for *\"what was true in March?\"*\n- Contradictions are **auto-detected** — storing a new decision auto-expires the old one\n- Query any point in time with `memory_since`\n\n---\n\n## Benchmarks\n\n### Recall Accuracy\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n| Strategy | Recall@5 | MRR |\n|---|---|---|\n| FTS5 keyword only | 31.3% | 31.3% |\n| **Semantic** (default) | **72.4%** | **82.5%** |\n| **Multi-strategy** | **74.5%** | **76.2%** |\n| + reranking (opt-in) | ~80%+ | ~85%+ |\n\n\u003c/td\u003e\n\u003ctd\u003e\n\nCorpus: 34 developer memories, 16 queries, 5 graph edges.\n\nReproduce: `npx vitest run benchmarks/`\n\n**Default: 72% Recall@5, 82% MRR** with local embeddings. Degrades gracefully to keyword matching (~31%) before model downloads.\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n### Search Latency — HNSW Vector Index\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n| Memories | HNSW | Brute-force | Speedup |\n|---|---|---|---|\n| 100 | 0.05ms | 0.10ms | 2x |\n| 1,000 | 0.06ms | 0.50ms | **8x** |\n| 5,000 | 0.08ms | 2.44ms | **30x** |\n| 10,000 | 0.08ms | 5.35ms | **67x** |\n\n\u003c/td\u003e\n\u003ctd\u003e\n\nMeasured: 100 searches averaged, 384-dim embeddings, top-10 results.\n\n**Sub-0.1ms at any scale** — effectively O(log n). HNSW is an optional dependency; brute-force is used as fallback when unavailable.\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## Tools Reference\n\n### Core Memory (7 tools)\n\n| Tool | Description |\n|---|---|\n| `memory_store` | Store a memory with type, tags, confidence. Auto-redacts private content, auto-expires contradictions. |\n| `memory_recall` | Semantic search — compact mode by default (~10x token savings). Use `memory_detail` for full content. |\n| `memory_detail` | Retrieve full content by ID after compact recall. |\n| `memory_context` | Load all relevant context for a topic, organized by type with token budgeting. |\n| `memory_extract` | Batch-save multiple memories from conversation. |\n| `memory_forget` | Delete by ID or query (with confirmation). |\n| `memory_inject` | Surface corrections + decisions + graph neighbors before coding starts. |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003ePrecision, History, Advanced, Reminders, and Maintenance tools (21 more)\u003c/strong\u003e\u003c/summary\u003e\n\n### Precision \u0026 History (5 tools)\n\n| Tool | Description |\n|---|---|\n| `memory_patch` | Surgical field-level edit with auto-snapshot. |\n| `memory_versions` | View full edit history or restore any version. |\n| `memory_search` | Exact full-text search via FTS5 with compact mode. |\n| `memory_since` | Temporal query with natural language ranges (`7d`, `2w`, `1h`). |\n| `memory_relate` | Build a typed knowledge graph between memories. |\n\n### Advanced (5 tools)\n\n| Tool | Description |\n|---|---|\n| `memory_multi_recall` | Multi-strategy search with compact mode: semantic + FTS5 + graph + temporal. |\n| `memory_tier` | Move memories between tiers: core / working / archival. |\n| `memory_expire` | Mark as no longer valid — preserved for history, excluded from recall. |\n| `memory_summarize` | Store structured session summary with decisions, corrections, metrics. |\n| `memory_history` | View past session summaries. |\n\n### Reminders (4 tools)\n\n| Tool | Description |\n|---|---|\n| `reminder_set` | Create reminder with optional deadline and scope. |\n| `reminder_list` | List active (or all) reminders, filterable by scope. |\n| `reminder_check` | Show overdue, today, and upcoming (7 days). |\n| `reminder_complete` | Mark as done (supports partial ID). |\n\n### Log \u0026 Maintenance (7 tools)\n\n| Tool | Description |\n|---|---|\n| `memory_log` | Append raw conversation turns (lossless, append-only). |\n| `memory_log_recall` | Search or replay log by session, keyword, or recency. |\n| `memory_log_cleanup` | Prune old entries with configurable retention. |\n| `memory_stats` | Counts, type breakdown, confidence distribution. |\n| `memory_export` | Export as Markdown or JSON. |\n| `memory_import` | Bulk import from JSON with automatic dedup. |\n| `memory_consolidate` | Merge duplicates, prune stale, promote frequent, decay idle. |\n\n\u003c/details\u003e\n\n---\n\n## Usage Guide\n\n### Storing Memories\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n**Natural language** (easiest)\n\n```\n\"Remember: we use PostgreSQL, not MongoDB\"\n\"Store a correction: never use console.log in production\"\n\"Note that the auth module is in src/auth/\"\n```\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n**Explicit tool calls**\n\n```js\nmemory_store({\n  content: \"Never use 'any' — define proper interfaces\",\n  type: \"correction\",\n  tags: [\"typescript\"],\n  confidence: 1.0\n})\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n### Recalling Memories\n\n```js\n// Step 1: Compact index — ~50-100 tokens (default)\nmemory_recall({ query: \"auth decisions\", limit: 5 })\n// -\u003e a1b2c3d4 [decision] Auth service uses JWT tokens... (92%)\n// -\u003e e5f6g7h8 [correction] Never store tokens in localStorage... (100%)\n\n// Step 2: Full details only for what you need\nmemory_detail({ ids: [\"a1b2c3d4\", \"e5f6g7h8\"] })\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eMore search options\u003c/strong\u003e\u003c/summary\u003e\n\n```js\n// Multi-strategy: semantic + FTS5 + graph + temporal\nmemory_multi_recall({\n  query: \"authentication architecture\",\n  limit: 10,\n  weights: { semantic: 0.4, fts: 0.3, graph: 0.15, temporal: 0.15 }\n})\n\n// Exact keyword search (FTS5 syntax)\nmemory_search({ query: \"OAuth PKCE\" })\nmemory_search({ query: '\"event sourcing\"' })     // phrase match\nmemory_search({ query: \"auth* NOT legacy\" })      // boolean\n```\n\n\u003c/details\u003e\n\n### Managing Memories\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eEdit, expire, promote, link\u003c/strong\u003e\u003c/summary\u003e\n\n```js\n// Surgical edit with auto-snapshot for rollback\nmemory_patch({ id: \"a1b2c3d4\", field: \"content\", value: \"Updated text\", reason: \"clarified\" })\n\n// View edit history / restore\nmemory_versions({ memory_id: \"a1b2c3d4\" })\n\n// Expire (preserve for history, exclude from recall)\nmemory_expire({ id: \"a1b2c3d4\", reason: \"Migrated to GraphQL\" })\n\n// Promote to core tier (always loaded at session start)\nmemory_tier({ id: \"a1b2c3d4\", tier: \"core\" })\n\n// Link related memories (graph builds itself, but you can add manual links)\nmemory_relate({ action: \"relate\", from_id: \"abc\", to_id: \"xyz\", relation_type: \"supports\" })\n```\n\nRelation types: `supports`, `contradicts`, `depends_on`, `supersedes`, `related_to`, `caused_by`, `implements` — or define your own.\n\n\u003c/details\u003e\n\n### Reminders\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCross-session deadline tracking\u003c/strong\u003e\u003c/summary\u003e\n\n```js\nreminder_set({ content: \"Review PR #42\", due_at: 1743033600000, scope: \"global\" })\n\nreminder_check({})\n// -\u003e [OVERDUE] Review PR #42\n// -\u003e [TODAY] Deploy auth service\n// -\u003e [upcoming] Write quarterly report\n\nreminder_complete({ id: \"a1b2c3d4\" })\n```\n\n\u003c/details\u003e\n\n### Privacy\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAutomatic redaction\u003c/strong\u003e\u003c/summary\u003e\n\n```js\n// Private blocks stripped before storage\nmemory_store({\n  content: \"DB password is \u003cprivate\u003ehunter2\u003c/private\u003e, connect to prod at db.example.com\",\n  type: \"topology\", tags: [\"database\"]\n})\n// Stored: \"DB password is [REDACTED], connect to prod at db.example.com\"\n\n// API keys, tokens, passwords auto-redacted by pattern matching\n// Configure patterns in ~/.amem/config.json\n```\n\n\u003c/details\u003e\n\n---\n\n## Platform Compatibility\n\n| Feature | Claude Code | GitHub Copilot CLI | Cursor / Windsurf / Other |\n|---|:---:|:---:|:---:|\n| One-command plugin install | Yes | Yes | -- |\n| 28 MCP tools | Yes | Yes | Yes |\n| AI skills | 14 | 7 | -- |\n| Auto-capture hooks | Yes | Yes | -- |\n| Session auto-summarize | Yes | Yes | -- |\n| Auto-memory sync | Yes | -- | -- |\n| CLI setup (`amem-cli init`) | Yes | Yes | Yes |\n\n**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.\n\n### AI Skills\n\n| What you say | Skill | Claude Code | Copilot CLI |\n|---|---|:---:|:---:|\n| *\"Remember never use any type\"* | `remember` | Yes | Yes |\n| *\"What do you remember about auth?\"* | `recall` | Yes | Yes |\n| *\"Load context for this task\"* | `context` | Yes | Yes |\n| *\"Show memory stats\"* | `stats` | Yes | Yes |\n| *\"Run memory doctor\"* | `doctor` | Yes | Yes |\n| *\"Export my memories\"* | `export` | Yes | Yes |\n| *\"List all corrections\"* | `list` | Yes | Yes |\n| *\"Sync my Claude memory\"* | `sync` | Yes | -- |\n| *\"Open the memory dashboard\"* | `dashboard` | Yes | -- |\n| *\"Install hooks\"* | `hooks` | Yes | -- |\n\n---\n\n## Working with Claude Code Auto-Memory\n\namem complements Claude's built-in auto-memory — it doesn't replace it.\n\n| | Claude auto-memory | amem |\n|---|---|---|\n| **Capture** | Automatic, zero config | Typed with confidence scores |\n| **Storage** | Single markdown file | SQLite with search, graph, temporal |\n| **Recall** | Entire file loaded every session | Only relevant memories surfaced |\n| **History** | Overwritten on update | Versioned, temporal validity |\n| **Search** | None | Semantic + FTS5 + graph + reranking |\n\n**Recommended:** Keep both enabled. Run `amem-cli sync` to import Claude's memories into amem for unified, structured access.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSync details\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\namem-cli sync              # Import all projects\namem-cli sync --dry-run    # Preview what would be imported\namem-cli sync --project myapp  # Import specific project\n```\n\n| Claude type | amem type | Confidence |\n|---|---|---|\n| `feedback` | `correction` | 1.0 |\n| `project` | `decision` | 0.85 |\n| `user` | `preference` | 0.8 |\n| `reference` | `topology` | 0.7 |\n\n\u003c/details\u003e\n\n---\n\n## Dashboard\n\n```bash\namem-cli dashboard              # Opens at localhost:3333\namem-cli dashboard --port=8080  # Custom port\n```\n\nMemory list with search and filters, inline actions (promote, demote, expire), interactive knowledge graph, confidence charts, session timeline, reminders, and conversation log.\n\n---\n\n## CLI Reference\n\n```bash\n# Setup\namem-cli init                          # Auto-configure AI tools\namem-cli rules                         # Generate extraction rules\namem-cli hooks                         # Install automatic capture hooks\namem-cli hooks --uninstall             # Remove hooks\namem-cli sync                          # Import Claude auto-memory\namem-cli doctor                        # Health diagnostics\namem-cli repair                        # Repair corrupted database from backups\n\n# Dashboard\namem-cli dashboard                     # Web dashboard (localhost:3333)\n\n# Memory operations\namem-cli recall \"authentication\"       # Semantic search\namem-cli stats                         # Statistics\namem-cli list --type correction        # List by type\namem-cli export --file memories.md     # Export to file\namem-cli forget abc12345               # Delete by short ID\namem-cli reset --confirm               # Wipe all data\n```\n\n---\n\n## Architecture\n\n```\n                        Your AI Tool\n           Claude Code / Copilot CLI / any MCP client\n                    |                |\n                    | MCP (stdio)    | Lifecycle Hooks\n                    v                v\n          +---------------------------------+\n          |        amem MCP Server          |\n          |                                 |\n          |  28 Tools . 7 Resources . 2 Prompts\n          |                                 |\n          |  Multi-Strategy Retrieval       |\n          |  [HNSW] + [FTS5] + [Graph] + [Temporal]\n          |       + query expansion         |\n          |       + cross-encoder (opt-in)  |\n          |                                 |\n          |  +---------------------------+  |\n          |  | SQLite + WAL + FTS5       |  |\n          |  | ~/.amem/memory.db         |  |\n          |  |                           |  |\n          |  | memories      (tiered)    |  |\n          |  | conversation_log (raw)    |  |\n          |  | memory_versions (history) |  |\n          |  | memory_relations (graph)  |  |\n          |  | session_summaries         |  |\n          |  | reminders                 |  |\n          |  +---------------------------+  |\n          |                                 |\n          |  Embeddings: bge-small-en-v1.5  |\n          |  Config: ~/.amem/config.json    |\n          +---------------------------------+\n```\n\n### Ranking Formula\n\n```\nscore = relevance x 0.45 + recency x 0.2 + confidence x 0.2 + importance x 0.15\n```\n\n| Factor | How it works |\n|---|---|\n| **Relevance** | Cosine similarity via HNSW index; query-expanded keyword fallback |\n| **Recency** | Exponential decay (`0.995^hours`) |\n| **Confidence** | Reinforced by repeated confirmation (0-1) |\n| **Importance** | Type-based: corrections `1.0` ... facts `0.4` |\n\nAdditive scoring ensures no single low factor kills the ranking.\n\n---\n\n## Configuration\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eEnvironment variables\u003c/strong\u003e\u003c/summary\u003e\n\n| Variable | Default | Description |\n|---|---|---|\n| `AMEM_DIR` | `~/.amem` | Storage directory |\n| `AMEM_DB` | `~/.amem/memory.db` | Database path |\n| `AMEM_PROJECT` | *(auto from git)* | Project scope override |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eConfig file (~/.amem/config.json)\u003c/strong\u003e\u003c/summary\u003e\n\nCreated automatically with defaults:\n\n```json\n{\n  \"retrieval\": {\n    \"semanticWeight\": 0.4,\n    \"ftsWeight\": 0.3,\n    \"graphWeight\": 0.15,\n    \"temporalWeight\": 0.15,\n    \"rerankerEnabled\": false\n  },\n  \"privacy\": {\n    \"enablePrivateTags\": true,\n    \"redactPatterns\": [\"...\"]\n  },\n  \"tiers\": {\n    \"coreMaxTokens\": 500,\n    \"workingMaxTokens\": 2000\n  },\n  \"hooks\": {\n    \"enabled\": true,\n    \"captureToolUse\": true,\n    \"captureSessionEnd\": true\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eVersion history\u003c/strong\u003e\u003c/summary\u003e\n\n### v0.18.0 — Progressive Disclosure \u0026 Scale\nHNSW 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.\n\n### v0.13.0 — World-Class Recall\nbge-small-en-v1.5 embeddings, additive scoring, query expansion, auto-relate knowledge graph, graph-aware injection, amem doctor, CI benchmarks.\n\n### v0.9.x — Temporal Intelligence\nTemporal validity, auto-expire contradictions, multi-strategy retrieval, cross-encoder reranking, memory tiers, privacy tags, lifecycle hooks, session summaries, dashboard, config system.\n\n### v0.7.0 — v0.8.0\nImport/export, confidence decay, embedding cache, multi-process safety, auto-configure CLI, dashboard.\n\n### v0.1.0 — v0.5.x\nCore store/recall, local embeddings, SQLite + WAL, consolidation, project scoping, reminders, conversation log, knowledge graph, FTS5, progressive disclosure.\n\n\u003c/details\u003e\n\n---\n\n## Tech Stack\n\n| Layer | Technology |\n|---|---|\n| Protocol | MCP SDK ^1.25 |\n| Language | TypeScript 5.6+, strict mode |\n| Database | SQLite + WAL + FTS5 |\n| Embeddings | HuggingFace bge-small-en-v1.5 (local, 80MB) + HNSW vector index |\n| Reranking | ms-marco-MiniLM-L-6-v2 (optional, local) |\n| Validation | Zod 3.25+ with `.strict()` schemas |\n| Testing | Vitest — 357 tests across 28 suites + recall benchmarks |\n| CI/CD | GitHub Actions, npm publish on release |\n\n---\n\n## Contributing\n\n```bash\ngit clone https://github.com/amanasmuei/amem.git\ncd amem \u0026\u0026 npm install\nnpm run build   # zero TS errors\nnpm test        # 357 tests pass\n```\n\nPRs must pass CI before merge. See [Issues](https://github.com/amanasmuei/amem/issues) for open tasks.\n\n---\n\n\u003cp align=\"center\"\u003e\n  Built by \u003ca href=\"https://github.com/amanasmuei\"\u003e\u003cstrong\u003eAman Asmuei\u003c/strong\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/amanasmuei/amem\"\u003eGitHub\u003c/a\u003e \u0026middot;\n  \u003ca href=\"https://www.npmjs.com/package/@aman_asmuei/amem\"\u003enpm\u003c/a\u003e \u0026middot;\n  \u003ca href=\"https://github.com/amanasmuei/amem/issues\"\u003eIssues\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eMIT License\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famanasmuei%2Famem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famanasmuei%2Famem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famanasmuei%2Famem/lists"}