@aman_asmuei/amem 0.22.0 → 0.23.0

package/README.md

@@ -1,117 +1,74 @@
 <p align="center">
-  <img src="assets/logo.png" alt="amem" width="160" />
+  <img src="assets/logo.png" alt="amem" width="140" />
 </p>
 
 <h1 align="center">amem</h1>
 
 <p align="center">
-  <strong>One memory. Every AI tool.</strong>
+  <strong>The memory layer for AI coding tools.</strong><br/>
+  <sub>Tell your AI once — it remembers everywhere.</sub>
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@aman_asmuei/amem"><img src="https://img.shields.io/npm/v/@aman_asmuei/amem?style=for-the-badge&logo=npm&logoColor=white&color=cb3837" alt="npm version" /></a>
-  &nbsp;
-  <a href="https://github.com/amanasmuei/amem/actions"><img src="https://img.shields.io/github/actions/workflow/status/amanasmuei/amem/ci.yml?style=for-the-badge&logo=github&label=CI" alt="CI status" /></a>
-  &nbsp;
-  <a href="https://github.com/amanasmuei/amem/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=for-the-badge" alt="MIT License" /></a>
-  &nbsp;
-  <img src="https://img.shields.io/badge/MCP-compatible-8A2BE2?style=for-the-badge" alt="MCP compatible" />
-  &nbsp;
-  <img src="https://img.shields.io/badge/node-%E2%89%A518-brightgreen?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js 18+" />
-</p>
-
-<p align="center">
-  Tell your AI something once — it remembers across Claude Code, GitHub Copilot, Cursor, Windsurf, and any MCP client.<br/>
-  Local-first &middot; Semantic search &middot; Knowledge graph &middot; Self-evolving &middot; Privacy-aware &middot; No cloud required.
+  <a href="https://www.npmjs.com/package/@aman_asmuei/amem"><img src="https://img.shields.io/npm/v/@aman_asmuei/amem?style=flat-square&logo=npm&logoColor=white&color=cb3837" alt="npm" /></a>
+  <a href="https://github.com/amanasmuei/amem/actions"><img src="https://img.shields.io/github/actions/workflow/status/amanasmuei/amem/ci.yml?style=flat-square&logo=github&label=CI" alt="CI" /></a>
+  <a href="https://github.com/amanasmuei/amem/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT" /></a>
+  <img src="https://img.shields.io/badge/MCP-compatible-8A2BE2?style=flat-square" alt="MCP" />
+  <img src="https://img.shields.io/badge/node-%E2%89%A518-brightgreen?style=flat-square&logo=node.js&logoColor=white" alt="Node 18+" />
 </p>
 
 <br/>
 
-<table align="center">
-  <tr>
-    <td><strong>94.8% R@5</strong><br/><sub>LongMemEval Oracle, 500q</sub></td>
-    <td><strong>0.08ms</strong><br/><sub>Search at 10k memories</sub></td>
-    <td><strong>29 MCP tools</strong><br/><sub>Full memory toolkit</sub></td>
-    <td><strong>Powered by</strong><br/><sub><a href="https://github.com/amanasmuei/amem-core">amem-core</a></sub></td>
-  </tr>
-</table>
+<div align="center">
 
-<br/>
+| 🎯 97.8% R@5 | ⚡ ~14ms p50 | 🛠 33 Tools | 🔒 100% Local |
+|:---:|:---:|:---:|:---:|
+| LongMemEval-S, 500q | Full recall pipeline | Complete memory toolkit | No cloud required |
+
+</div>
 
 <p align="center">
-  <a href="#-quick-start">Quick Start</a> &bull;
-  <a href="#-how-it-works">How It Works</a> &bull;
-  <a href="#-benchmarks">Benchmarks</a> &bull;
-  <a href="#-tools-reference">Tools</a> &bull;
-  <a href="#-usage-guide">Usage Guide</a> &bull;
+  <a href="#-quick-start">Quick Start</a> · 
+  <a href="#-how-it-works">How It Works</a> · 
+  <a href="#-benchmarks">Benchmarks</a> · 
+  <a href="#%EF%B8%8F-tools-reference">Tools</a> · 
+  <a href="#-dashboard--knowledge-graph">Dashboard</a> · 
   <a href="#-architecture">Architecture</a>
 </p>
 
 ---
 
-## Why amem?
+## 💡 The Problem
 
 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.
+```diff
+- You: "Don't use 'any' in TypeScript"     → told Claude 3 times. Copilot still doesn't know.
+- You: "We chose PostgreSQL over MongoDB"   → explained in Cursor. Claude has no idea.
++ With amem: tell it once, every AI tool remembers — forever.
+```
 
-**amem** gives all your AI tools a shared, persistent memory.
+<details>
+<summary><b>See it in action</b></summary>
 
 ```
 You (in Claude Code):  "Don't use any type in TypeScript"
-  amem stores this as a correction (priority 1.0)
+  └─ amem stores this as a correction (priority 1.0, confidence 100%)
 
 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.
-
----
-
-## 🧬 Powered by `amem-core`
-
-`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`](https://github.com/amanasmuei/amem-core).
+  └─ Copilot already knows — amem feeds it the same correction
 
+You (open Cursor): "What do you remember about TypeScript?"
+  └─ Instantly recalls: "Don't use any type" + all related preferences
 ```
-        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.
+</details>
 
-> 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.
+No cloud. No API keys. One SQLite file. Everything stays on your machine.
 
 ---
 
-## Quick Start
+## 🚀 Quick Start
 
 <table>
 <tr>
@@ -139,7 +96,7 @@ copilot plugin install amem
 </table>
 
 <details>
-<summary><strong>Cursor / Windsurf / Any MCP Client</strong></summary>
+<summary><b>📦 Cursor / Windsurf / Any MCP Client</b></summary>
 
 ```bash
 npm install -g @aman_asmuei/amem
@@ -147,7 +104,7 @@ amem-cli init      # Detects & configures all installed AI tools
 amem-cli rules     # Generates extraction rules for proactive memory use
 ```
 
-Or configure manually:
+Or add to your MCP config manually:
 
 ```json
 {
@@ -168,13 +125,58 @@ Or configure manually:
 amem-cli stats     # Should show "0 memories" initially
 ```
 
-Tell your AI: *"Remember: always use strict TypeScript, never use any type"*
+> 💬 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.
+
+---
+
+## 🧬 Powered by `amem-core`
 
-Start a **new** session: *"What do you remember about TypeScript?"* — it recalls instantly.
+`amem` is the MCP server. The retrieval engine lives in [`@aman_asmuei/amem-core`](https://github.com/amanasmuei/amem-core).
+
+```
+     Claude Code / Copilot / Cursor / any MCP client
+                        │
+                        │ MCP (stdio)
+                        ▼
+        ┌──────────────────────────────────┐
+        │  @aman_asmuei/amem  (this pkg)   │
+        │  33 Tools · 7 Resources · 2 Prompts
+        │  CLI · Hooks · Dashboard         │
+        └───────────────┬──────────────────┘
+                        │ imports
+                        ▼
+        ┌──────────────────────────────────┐
+        │  @aman_asmuei/amem-core          │
+        │  Embeddings · HNSW · Recall      │
+        │  Knowledge Graph · Reflection    │
+        │  97.8% R@5 on LongMemEval-S      │
+        └───────────────┬──────────────────┘
+                        ▼
+              ┌────────────────────┐
+              │  SQLite + WAL      │
+              │  ~/.amem/memory.db │
+              └────────────────────┘
+```
+
+<details>
+<summary><b>Why two packages?</b></summary>
+
+| Package | Role | Install |
+|---|---|---|
+| **`@aman_asmuei/amem`** *(this)* | MCP server + CLI + hooks | `npm i -g @aman_asmuei/amem` |
+| [**`@aman_asmuei/amem-core`**](https://github.com/amanasmuei/amem-core) | Pure TS library, zero MCP deps | `npm i @aman_asmuei/amem-core` |
+
+The same engine powers `amem` (MCP server), `aman-agent` (CLI), `aman-tg` (Telegram bot), and any Node app you give memory to. Retrieval improvements ship via `amem-core`. MCP-tool changes ship via `amem`. They version independently.
+
+> The **97.8% R@5** headline is the engine quality from `amem-core` (LongMemEval-S, session-level, 500 questions, zero API calls) — exactly what you get whether you call it through MCP or import the library directly.
+
+</details>
 
 ---
 
-## How It Works
+## ⚙️ How It Works
 
 amem captures knowledge in **three layers** — from fully automatic to fully manual:
 
@@ -197,6 +199,9 @@ amem captures knowledge in **three layers** — from fully automatic to fully ma
 
 Corrections always surface first — they are your AI's hard constraints.
 
+<details>
+<summary><b>🔄 Memory Tiers & Temporal Validity</b></summary>
+
 ### Memory Tiers
 
 | Tier | Behavior |
@@ -212,7 +217,10 @@ Memories aren't forever. When facts change:
 - Contradictions are **auto-detected** ��� storing a new decision auto-expires the old one
 - Query any point in time with `memory_since`
 
-### Self-Evolving Memory Loop
+</details>
+
+<details>
+<summary><b>🧠 Self-Evolving Memory Loop</b></summary>
 
 Your memory doesn't just store — it **learns from its own structure**. Call `memory_reflect` to trigger the reflection engine:
 
@@ -236,7 +244,7 @@ memory_reflect → Analyzes your entire memory graph
 The system auto-nudges when reflection is due (>7 days or >50 new memories since last run).
 
 <details>
-<summary><strong>What the reflection report looks like</strong></summary>
+<summary><b>📊 What the reflection report looks like</b></summary>
 
 ```
 # Memory Reflection Report
@@ -276,40 +284,67 @@ Health Score: 68/100
 
 ---
 
-## Benchmarks
+## 📈 Benchmarks
 
-### Recall Accuracy
+### Recall Accuracy (LongMemEval)
+
+All numbers from [`amem-core` v0.5.1](https://github.com/amanasmuei/amem-core) — the retrieval engine powering this MCP server. Zero API calls, all local, fully reproducible.
 
 <table>
 <tr>
 <td>
 
-| 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%+ |
+**LongMemEval-S (session-level) — headline metric**
+
+| Metric | Score |
+|:---:|:---:|
+| **R@1** | **95.0%** |
+| **R@3** | **97.0%** |
+| **R@5** | **🏆 97.8%** |
+| **R@10** | **99.0%** |
+
+500 questions · CPU only · zero API calls
 
 </td>
 <td>
 
-Corpus: 34 developer memories, 16 queries, 5 graph edges.
+**LongMemEval Oracle (turn-level)**
 
-Reproduce: `npx vitest run benchmarks/`
+| Metric | Score |
+|:---:|:---:|
+| **R@1** | **66.2%** |
+| **R@3** | **90.8%** |
+| **R@5** | **94.6%** |
+| **R@10** | **97.5%** |
 
-**Default: 72% Recall@5, 82% MRR** with local embeddings. Degrades gracefully to keyword matching (~31%) before model downloads.
+479 scoreable questions · 301s runtime · Node 22
 
 </td>
 </tr>
 </table>
 
-### Search Latency — HNSW Vector Index
+Pipeline: local `bge-small-en-v1.5` bi-encoder + `ms-marco-MiniLM-L-6-v2` cross-encoder (int8, batched, default-on). See [amem-core benchmarks](https://github.com/amanasmuei/amem-core#-benchmarks) for full per-type breakdowns, pipeline evolution, and honest notes.
+
+### Search Latency
 
 <table>
 <tr>
 <td>
 
+**Full recall pipeline (v0.5.1+)**
+
+| Stage | p50 | Share |
+|---|---|---|
+| Embed (bi-encoder) | 3.0ms | 22% |
+| Retrieve (HNSW + multi-strategy) | 0.1ms | 1% |
+| **Rerank (int8 cross-encoder)** | **10.3ms** | **74%** |
+| **Total** | **~14ms** | 100% |
+
+</td>
+<td>
+
+**HNSW index only (vector search)**
+
 | Memories | HNSW | Brute-force | Speedup |
 |---|---|---|---|
 | 100 | 0.05ms | 0.10ms | 2x |
@@ -330,7 +365,7 @@ Measured: 100 searches averaged, 384-dim embeddings, top-10 results.
 
 ---
 
-## Tools Reference
+## 🛠️ Tools Reference
 
 ### Core Memory (7 tools)
 
@@ -345,7 +380,7 @@ Measured: 100 searches averaged, 384-dim embeddings, top-10 results.
 | `memory_inject` | Surface corrections + decisions + graph neighbors before coding starts. |
 
 <details>
-<summary><strong>Precision, History, Advanced, Reminders, and Maintenance tools (22 more)</strong></summary>
+<summary><strong>Precision, History, Advanced, Admin, Reminders, and Maintenance tools (26 more)</strong></summary>
 
 ### Precision & History (5 tools)
 
@@ -368,6 +403,15 @@ Measured: 100 searches averaged, 384-dim embeddings, top-10 results.
 | `memory_history` | View past session summaries. |
 | `memory_reflect` | Self-evolving reflection engine — clusters memories, detects contradictions, identifies synthesis candidates, surfaces knowledge gaps. |
 
+### Admin & Sync (4 tools)
+
+| Tool | Description |
+|---|---|
+| `memory_doctor` | Run read-only health diagnostics on the amem database. |
+| `memory_repair` | Perform safe, targeted repairs on the amem database. |
+| `memory_config` | Get or set amem configuration with safety guardrails. |
+| `memory_sync` | Import or export memories between amem and other systems (Claude auto-memory, Copilot instructions). |
+
 ### Reminders (4 tools)
 
 | Tool | Description |
@@ -393,7 +437,7 @@ Measured: 100 searches averaged, 384-dim embeddings, top-10 results.
 
 ---
 
-## Usage Guide
+## 📖 Usage Guide
 
 ### Storing Memories
 
@@ -523,22 +567,90 @@ memory_store({
 
 ---
 
-## Platform Compatibility
+## ⚔️ Honest Comparison: amem vs graphify
+
+<details>
+<summary><b>Click to expand — how amem compares to graphify</b></summary>
+
+[graphify](https://github.com/safishamsi/graphify) is the most common "what about X?" when people find amem. They solve **fundamentally different problems** and are genuinely complementary.
+
+### What each tool does
+
+| | **amem** | **graphify** |
+|---|---|---|
+| **One-liner** | Persistent memory across AI sessions | Codebase → knowledge graph |
+| **Core question** | *"What has my AI learned about me?"* | *"What does this codebase look like?"* |
+| **Input** | Natural language (corrections, decisions, preferences) | Files (code, docs, PDFs, images, video) |
+| **Output** | Recalled memories ranked by relevance | Structural graph + report + interactive HTML |
+| **Persistence** | Always — memory survives across sessions and tools | Snapshot — `graph.json` persists, but doesn't learn over time |
+| **When it runs** | Continuously, every session | On-demand (`/graphify .`) or on commit via git hook |
+
+### Technical comparison
+
+| | **amem** | **graphify** |
+|---|---|---|
+| **Runtime** | TypeScript / Node (≥18) | Python (≥3.10) |
+| **Protocol** | MCP server (33 tools, 7 resources) | AI skill (slash command) + optional MCP server |
+| **Storage** | SQLite + FTS5 + WAL | NetworkX graph → JSON file |
+| **Search** | Semantic embeddings + FTS5 + graph + reranking | Graph traversal (BFS/DFS) + node lookup |
+| **Embeddings** | Local `bge-small-en-v1.5` (384-dim) | None — uses graph topology, not vector similarity |
+| **Code understanding** | None — stores what you tell it | Deep — tree-sitter AST for 25 languages |
+| **Multimodal** | Text only | Code, docs, PDFs, images, video, audio |
+| **LLM required** | No (all local) | Yes for docs/images (code is LLM-free via tree-sitter) |
+| **Benchmark** | 97.8% R@5 on LongMemEval-S | 71.5x token reduction vs raw file reading |
+| **AI tool support** | Claude Code, Copilot, Cursor, any MCP client | Claude Code, Codex, Copilot, Cursor, Gemini, Aider, Kiro, +10 more |
+
+### Where each wins
+
+**amem wins at:**
+- Remembering your preferences, corrections, and decisions **across projects and tools**
+- Semantic recall — finding the right memory from a vague query (97.8% R@5)
+- Temporal intelligence — tracking what was true *when*, auto-expiring contradictions
+- Self-evolution — reflection engine clusters, detects contradictions, identifies gaps
+- Zero LLM dependency — everything runs locally, no API calls
+
+**graphify wins at:**
+- Understanding **code structure** — call graphs, imports, class hierarchies, cross-file relationships
+- Multimodal ingestion — drop in code, papers, screenshots, videos, it graphs them all
+- Token efficiency — 71.5x compression means your AI reads structure, not raw files
+- Breadth of language support — 25 programming languages via tree-sitter AST
+- Breadth of AI tool support — 15+ platforms with dedicated install commands
+
+### Honest takeaways
+
+1. **They don't compete.** amem remembers *your* knowledge (decisions, corrections, preferences). graphify maps *the codebase's* structure (call graphs, dependencies, architecture). Different data, different access patterns.
+
+2. **Use both if you want.** Run `graphify .` to get a structural map of your project. Use amem to remember "we chose this architecture because X." The graph tells your AI *what exists*. The memory tells it *why things are that way*.
+
+3. **graphify has broader platform coverage** (15+ AI tools). amem has deeper integration where it works (MCP protocol with 33 tools, structured resources, prompts).
+
+4. **graphify needs an LLM for non-code files.** amem is fully local — no API calls, no model inference beyond the local embedding model.
+
+5. **The real choice depends on your pain point.** If your AI keeps forgetting your preferences and decisions → amem. If your AI can't navigate your codebase efficiently → graphify. If both → use both.
+
+</details>
+
+---
+
+## 🌐 Platform Compatibility
 
 | Feature | Claude Code | GitHub Copilot CLI | Cursor / Windsurf / Other |
 |---|:---:|:---:|:---:|
 | One-command plugin install | Yes | Yes | -- |
-| 29 MCP tools | Yes | Yes | Yes |
+| 33 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.
+**Claude Code** has the deepest integration (plugin + hooks + auto-memory sync). **Copilot CLI** is a close second. **Other MCP clients** get the full 33-tool server via manual config.
 
 ### AI Skills
 
+<details>
+<summary><b>Available skills by platform</b></summary>
+
 | What you say | Skill | Claude Code | Copilot CLI |
 |---|---|:---:|:---:|
 | *"Remember never use any type"* | `remember` | Yes | Yes |
@@ -552,9 +664,11 @@ memory_store({
 | *"Open the memory dashboard"* | `dashboard` | Yes | -- |
 | *"Install hooks"* | `hooks` | Yes | -- |
 
+</details>
+
 ---
 
-## Working with Claude Code Auto-Memory
+## 🔄 Working with Claude Code Auto-Memory
 
 amem complements Claude's built-in auto-memory — it doesn't replace it.
 
@@ -615,18 +729,24 @@ Claude Code → amem sync → amem DB → amem sync --to copilot → copilot-ins
 
 ---
 
-## Dashboard
+## 📊 Dashboard & Knowledge Graph
 
 ```bash
 amem-cli dashboard              # Opens at localhost:3333
 amem-cli dashboard --port=8080  # Custom port
 ```
 
-Memory 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.
+Full-featured web dashboard with:
+
+- 🔍 **Memory browser** — search, filter by type/tier/source, inline actions (promote, demote, expire)
+- 🕸️ **Interactive knowledge graph** — zoom, pan, click-to-focus with neighborhood highlighting, detail panel, search, directional edges
+- 📈 **Analytics** — confidence distribution, type breakdown, session timeline
+- ⏰ **Reminders** — view and manage cross-session tasks
+- 📋 **Copilot Preview** — see what would be exported to `copilot-instructions.md`
 
 ---
 
-## CLI Reference
+## 💻 CLI Reference
 
 ```bash
 # Setup
@@ -654,7 +774,7 @@ amem-cli reset --confirm               # Wipe all data
 
 ---
 
-## Architecture
+## 🏗 Architecture
 
 ```
                         Your AI Tool
@@ -665,7 +785,7 @@ amem-cli reset --confirm               # Wipe all data
           ┌─────────────────────────────────┐
           │   @aman_asmuei/amem             │  ← this package
           │                                 │
-          │  29 Tools · 7 Resources · 2 Prompts
+          │  33 Tools · 7 Resources · 2 Prompts
           │  Slash commands · CLI · Hooks   │
           │  Config: ~/.amem/config.json    │
           └────────────────┬────────────────┘
@@ -677,14 +797,15 @@ amem-cli reset --confirm               # Wipe all data
           │  Multi-Strategy Retrieval       │
           │  [HNSW] + [FTS5] + [Graph] + [Temporal]
           │       + query expansion         │
-          │       + cross-encoder (opt-in)  │
+          │       + cross-encoder reranker   │
           │                                 │
           │  Self-Evolving Reflection       │
           │  [Clustering] + [Contradictions]│
           │  + [Synthesis] + [Gap Detection]│
           │                                 │
           │  Embeddings: bge-small-en-v1.5  │
-          │  94.8% R@5 on LongMemEval       │
+          │  Reranker: ms-marco-MiniLM int8 │
+          │  97.8% R@5 on LongMemEval-S     │
           └────────────────┬────────────────┘
                            │
                            ▼
@@ -722,7 +843,7 @@ Additive scoring ensures no single low factor kills the ranking.
 
 ---
 
-## Configuration
+## ⚙️ Configuration
 
 <details>
 <summary><strong>Environment variables</strong></summary>
@@ -747,7 +868,7 @@ Created automatically with defaults:
     "ftsWeight": 0.3,
     "graphWeight": 0.15,
     "temporalWeight": 0.15,
-    "rerankerEnabled": false
+    "rerankerEnabled": true
   },
   "privacy": {
     "enablePrivateTags": true,
@@ -768,7 +889,10 @@ Created automatically with defaults:
 </details>
 
 <details>
-<summary><strong>Version history</strong></summary>
+<summary><strong>📋 Version history</strong></summary>
+
+### v0.23.0 — Interactive Knowledge Graph Dashboard
+Full-width graph explorer with zoom/pan, click-to-focus neighborhood highlighting, detail panel with relation navigation, search & filter, directional edges, force-directed layout. Admin tools (doctor, repair, config, sync). 255 tests across 18 suites.
 
 ### v0.19.0 — Self-Evolving Memory Loop
 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.
@@ -792,7 +916,7 @@ Core store/recall, local embeddings, SQLite + WAL, consolidation, project scopin
 
 ---
 
-## Tech Stack
+## 🧰 Tech Stack
 
 | Layer | Technology |
 |---|---|
@@ -800,36 +924,38 @@ Core store/recall, local embeddings, SQLite + WAL, consolidation, project scopin
 | 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) |
+| Reranking | ms-marco-MiniLM-L-6-v2 (default-on, int8, batched, local) |
 | Validation | Zod 3.25+ with `.strict()` schemas |
-| Testing | Vitest — 388 tests across 29 suites + recall benchmarks |
+| Testing | Vitest — 281 tests across 19 suites + recall benchmarks |
 | CI/CD | GitHub Actions, npm publish on release |
 
 ---
 
-## Contributing
+## 🤝 Contributing
 
 ```bash
 git clone https://github.com/amanasmuei/amem.git
 cd amem && npm install
 npm run build   # zero TS errors
-npm test        # 388 tests pass
+npm test        # 281 tests pass
 ```
 
 PRs must pass CI before merge. See [Issues](https://github.com/amanasmuei/amem/issues) for open tasks.
 
+<br/>
+
 ---
 
 <p align="center">
-  Built with ❤️ in 🇲🇾 Malaysia by <a href="https://github.com/amanasmuei"><strong>Aman Asmuei</strong></a>
+  <sub>Built with ❤️ in 🇲🇾 Malaysia by <a href="https://github.com/amanasmuei"><strong>Aman Asmuei</strong></a></sub>
 </p>
 
 <p align="center">
-  <a href="https://github.com/amanasmuei/amem">GitHub</a> &middot;
-  <a href="https://www.npmjs.com/package/@aman_asmuei/amem">npm</a> &middot;
-  <a href="https://github.com/amanasmuei/amem/issues">Issues</a>
+  <a href="https://github.com/amanasmuei/amem"><img src="https://img.shields.io/badge/GitHub-repo-181717?style=flat-square&logo=github" alt="GitHub" /></a>
+  <a href="https://www.npmjs.com/package/@aman_asmuei/amem"><img src="https://img.shields.io/badge/npm-package-cb3837?style=flat-square&logo=npm&logoColor=white" alt="npm" /></a>
+  <a href="https://github.com/amanasmuei/amem/issues"><img src="https://img.shields.io/badge/Issues-report-orange?style=flat-square&logo=github" alt="Issues" /></a>
 </p>
 
 <p align="center">
-  <sub>MIT License</sub>
+  <sub>MIT License · Star ⭐ if amem saves your AI from amnesia</sub>
 </p>

package/dist/cli.js

@@ -51,7 +51,16 @@ if (command === "hooks") {
 }
 if (command === "sync") {
     await handleSync(args.slice(1));
-    process.exit(0);
+    // Workaround: @huggingface/transformers (ONNX Runtime) has a known
+    // teardown crash on macOS — worker threads try to release a mutex that
+    // Node has already torn down, producing
+    //   libc++abi: terminating ... mutex lock failed: Invalid argument
+    // and exit code 134. By this point all sync work is committed and the
+    // DB is closed, so we flush stdio and hard-exit via SIGKILL before the
+    // broken native destructors can run.
+    await new Promise((resolve) => process.stdout.write("", () => resolve()));
+    await new Promise((resolve) => process.stderr.write("", () => resolve()));
+    process.kill(process.pid, "SIGKILL");
 }
 // ── Commands that need a database ───────────────────────
 if (command === "doctor") {
@@ -658,11 +667,11 @@ function handleReset(db, args) {
     try {
         fs.unlinkSync(DB_PATH + "-wal");
     }
-    catch { }
+    catch { /* WAL file may not exist */ }
     try {
         fs.unlinkSync(DB_PATH + "-shm");
     }
-    catch { }
+    catch { /* SHM file may not exist */ }
     console.log("All amem data has been wiped. Starting fresh.");
     console.log(`Deleted: ${DB_PATH}`);
 }