Fix correctness, durability, and API parity fixes across all subsystems

README.md

@@ -80,6 +80,7 @@ Then allow the MCP tools so Claude can use them without prompting each time. Add
       "mcp__recalld__forget_memory",
       "mcp__recalld__find_similar_memories",
       "mcp__recalld__create_namespace",
+      "mcp__recalld__namespace_stats",
       "mcp__recalld__list_memories"
     ]
   }
@@ -172,7 +173,7 @@ See [docs/benchmark.md](docs/benchmark.md) for full methodology, per-category br
 
 ## Usage modes
 
-**MCP server (stdio)** -- Runs as a Model Context Protocol server for AI tools like Claude Code. Exposes 9 tools: `store_memory`, `store_memories`, `recall_memories`, `get_memory`, `reinforce_memory`, `forget_memory`, `find_similar_memories`, `create_namespace`, `list_memories`.
+**MCP server (stdio)** -- Runs as a Model Context Protocol server for AI tools like Claude Code. Exposes 10 tools: `store_memory`, `store_memories`, `recall_memories`, `get_memory`, `reinforce_memory`, `forget_memory`, `find_similar_memories`, `create_namespace`, `namespace_stats`, `list_memories`.
 
 ```sh
 recalld mcp

docs/architecture.md

@@ -44,7 +44,7 @@ graph TD
 
     subgraph STORE["Storage Engine"]
         META["meta.db"]
-        VEC["vectors.dat"]
+        VEC["<ns>/vectors.dat"]
         TXT["fulltext.dat"]
         EDGES["edges.db"]
     end
@@ -90,16 +90,16 @@ Shutdown is the reverse: signal background tasks, drain in-flight requests (5s t
 
 ### Core storage files
 
-All data lives in a single directory (default: `~/.recalld/data/`). An exclusive file lock (`recalld.lock`) prevents multi-process access. There are four primary data files (meta.db, vectors.dat, fulltext.dat, edges.db) plus the FTS5 index (fts.db) and the lock file.
+All data lives in a single directory (default: `~/.recalld/data/`). An exclusive file lock (`recalld.lock`) prevents multi-process access. There are four primary data stores (meta.db, `<namespace>/vectors.dat`, fulltext.dat, edges.db) plus the FTS5 index (fts.db) and the lock file.
 
 ```
 ~/.recalld/data/
   recalld.lock        # flock() exclusive lock
   meta.db             # redb B+tree -- memory records + secondary indexes
   fulltext.dat            # append-only CRC32 log -- full_text payloads
   edges.db            # redb B+tree -- graph edge persistence
-  ns_default.dat      # mmap'd vector file for "default" namespace
-  ns_work.dat         # mmap'd vector file for "work" namespace (example)
+  default/vectors.dat # mmap'd vector file for "default" namespace
+  work/vectors.dat    # mmap'd vector file for "work" namespace (example)
   fts.db              # SQLite FTS5 full-text search index
 ```
 
@@ -122,7 +122,7 @@ Configured with a 16 MB read cache covering top B+tree levels.
 
 #### vectors.dat (per-namespace, mmap)
 
-Each namespace gets its own memory-mapped vector file (`ns_<name>.dat`). Vectors are stored in fixed-size slots for O(1) random access.
+Each namespace gets its own subdirectory containing a memory-mapped `vectors.dat` file (e.g., `default/vectors.dat`, `work/vectors.dat`). Vectors are stored in fixed-size slots for O(1) random access.
 
 **File format:**
 
@@ -174,10 +174,10 @@ Persists graph edges separately from memory records. Composite keys enable effic
 
 Both directions are stored for O(1) neighbor lookups in either direction. Orphaned edges (referencing deleted memories) are cleaned up on startup.
 
-### Why four files
+### Why four stores
 
 - **meta.db**: needs transactions, range scans, secondary indexes -> embedded B+tree (redb).
-- **vectors.dat**: needs zero-copy reads of large float arrays, O(1) slot access -> mmap.
+- **`<ns>/vectors.dat`**: needs zero-copy reads of large float arrays, O(1) slot access -> mmap (one file per namespace).
 - **fulltext.dat**: large variable-length blobs, append-only pattern -> log-structured file.
 - **edges.db**: could live in meta.db, but separated to avoid write amplification -- edges are written frequently (auto-linking) while metadata records are written infrequently after creation.
 

docs/guide.md

@@ -746,7 +746,7 @@ Shows decay forecast, at-risk memories, and storage breakdown.
 
 ## 6. MCP Tools Reference
 
-recalld exposes 9 MCP tools. These are available to any MCP client (Claude Code, Cursor, etc.) when recalld is configured as an MCP server.
+recalld exposes 10 MCP tools. These are available to any MCP client (Claude Code, Cursor, etc.) when recalld is configured as an MCP server.
 
 ### `store_memory`
 
@@ -842,6 +842,14 @@ Create a new memory namespace.
 | `desiredRetention` | number | No | Target retention rate 0.0-1.0 (default: 0.9). |
 | `decayRateMultiplier` | number | No | Per-namespace decay rate multiplier. 1.0 = normal, 2.0 = 2x slower, 0.0 = disabled. Omit to inherit global setting. |
 
+### `namespace_stats`
+
+Get statistics for a memory namespace including total memory count, phase breakdown (full/summary/ghost), permastore count, average strength, edge count, and vector storage size.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `namespace` | string | No | Namespace name to get stats for (default: `"default"`). |
+
 ### `list_memories`
 
 List memories in a namespace with pagination and optional filters. Unlike `recall_memories`, this does not require a search query -- it returns memories sorted by creation date (newest first).

docs/mcp.md

@@ -46,6 +46,7 @@ By default, Claude Code will prompt you for approval each time an MCP tool is ca
       "mcp__recalld__forget_memory",
       "mcp__recalld__find_similar_memories",
       "mcp__recalld__create_namespace",
+      "mcp__recalld__namespace_stats",
       "mcp__recalld__list_memories"
     ]
   }
@@ -131,8 +132,7 @@ Response:
   "phase": "Full",
   "strength": 1.0,
   "stability": 3.7145,
-  "createdAt": 1719187200000,
-  "createdAtFormatted": "2025-06-24 00:00:00 UTC"
+  "createdAt": "2025-06-24 00:00:00 UTC"
 }
 ```
 
@@ -196,7 +196,7 @@ Response:
       "phase": "Full",
       "strength": 1.0,
       "stability": 3.7145,
-      "createdAt": 1719187200000
+      "createdAt": "2025-06-24 00:00:00 UTC"
     },
     {
       "index": 1,
@@ -205,7 +205,7 @@ Response:
       "phase": "Full",
       "strength": 1.0,
       "stability": 3.7145,
-      "createdAt": 1719187200000
+      "createdAt": "2025-06-24 00:00:00 UTC"
     }
   ],
   "total": 2,
@@ -281,10 +281,8 @@ Response (compact=false):
       "topics": ["coding-style"],
       "phase": "Full",
       "strength": 0.95,
-      "createdAt": 1719187200000,
-      "createdAtFormatted": "2025-06-24 00:00:00 UTC",
-      "lastAccessedAt": 1719273600000,
-      "lastAccessedAtFormatted": "2025-06-25 00:00:00 UTC"
+      "createdAt": "2025-06-24 00:00:00 UTC",
+      "lastAccessedAt": "2025-06-25 00:00:00 UTC"
     }
   ],
   "count": 1,
@@ -341,10 +339,8 @@ Response:
   "phase": "Full",
   "strength": 0.95,
   "stability": 12.4,
-  "createdAt": 1719187200000,
-  "createdAtFormatted": "2025-06-24 00:00:00 UTC",
-  "lastAccessedAt": 1719273600000,
-  "lastAccessedAtFormatted": "2025-06-25 00:00:00 UTC",
+  "createdAt": "2025-06-24 00:00:00 UTC",
+  "lastAccessedAt": "2025-06-25 00:00:00 UTC",
   "isPermastore": false,
   "edgeCount": 3
 }
@@ -470,8 +466,8 @@ Response:
       "tags": ["type/project", "tech/rust"],
       "phase": "Full",
       "strength": 0.88,
-      "createdAt": 1719100800000,
-      "lastAccessedAt": 1719187200000
+      "createdAt": "2025-06-23 00:00:00 UTC",
+      "lastAccessedAt": "2025-06-24 00:00:00 UTC"
     }
   ],
   "count": 1
@@ -497,16 +493,19 @@ Response:
   "namespace": "default",
   "threshold": 0.9,
   "clusters": [
-    [
-      {
-        "id": "a1b2c3d4-...",
-        "summary": "User prefers snake_case in Rust"
-      },
-      {
-        "id": "c3d4e5f6-...",
-        "summary": "User likes snake_case for Rust code"
-      }
-    ]
+    {
+      "memories": [
+        {
+          "id": "a1b2c3d4-...",
+          "summary": "User prefers snake_case in Rust"
+        },
+        {
+          "id": "c3d4e5f6-...",
+          "summary": "User likes snake_case for Rust code"
+        }
+      ],
+      "maxSimilarity": 0.92
+    }
   ],
   "clusterCount": 1
 }
@@ -548,8 +547,47 @@ Response:
   "name": "work-project",
   "embeddingDim": 1536,
   "memoryCount": 0,
-  "createdAt": 1719187200000,
-  "createdAtFormatted": "2025-06-24 00:00:00 UTC"
+  "createdAt": "2025-06-24 00:00:00 UTC"
+}
+```
+
+---
+
+### namespace_stats
+
+Get statistics for a memory namespace including total memory count, phase breakdown (full/summary/ghost), permastore count, average strength, edge count, and vector storage size. Use this to check how many memories exist or monitor namespace health.
+
+#### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `namespace` | string | no | `"default"` | Namespace name to get stats for |
+
+#### Example
+
+Request:
+
+```json
+{
+  "namespace": "default"
+}
+```
+
+Response:
+
+```json
+{
+  "namespace": "default",
+  "totalMemories": 42,
+  "phases": {
+    "full": 30,
+    "summary": 8,
+    "ghost": 4
+  },
+  "permastoreCount": 3,
+  "averageStrength": 0.72,
+  "edgeCount": 156,
+  "vectorStorageBytes": 1048576
 }
 ```
 
@@ -591,15 +629,12 @@ Response:
     {
       "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
       "summary": "User prefers snake_case for Rust code and camelCase for TypeScript",
-      "namespace": "default",
-      "tags": ["type/user-profile", "tech/rust", "tech/typescript"],
-      "phase": "Full",
-      "strength": 0.95,
-      "createdAt": 1719187200000,
-      "createdAtFormatted": "2025-06-24 00:00:00 UTC"
+      "entities": ["TypeScript"],
+      "topics": ["coding-style"],
+      "createdAt": "2025-06-24 00:00:00 UTC"
     }
   ],
-  "count": 1,
+  "total": 1,
   "limit": 10,
   "offset": 0
 }