@exaudeus/memory-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Etienne Beaulac
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,264 @@
+# Memory MCP
+
+A Model Context Protocol (MCP) server that gives AI coding agents persistent, evolving knowledge about a codebase. Instead of starting cold every session, agents can store and retrieve observations about architecture, conventions, gotchas, and recent work context.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `memory_context` | Session start AND pre-task lookup. Call with no args for user + preferences + stale nudges; call with `context` for task-specific knowledge |
+| `memory_query` | Structured search with brief/standard/full detail levels and AND/OR/NOT filter syntax. Scope defaults to `"*"` (all topics) |
+| `memory_store` | Store a knowledge entry with dedup detection, preference surfacing, and lobe auto-detection from file paths |
+| `memory_correct` | Correct, update, or delete an existing entry (suggests storing as preference) |
+| `memory_bootstrap` | First-use scan to seed knowledge from repo structure, README, and build files |
+
+> **Hidden tools** (still callable, not in the catalog — agents learn about them from hints/errors):
+> `memory_list_lobes` (lobe paths and stats), `memory_stats` (entry counts, freshness, storage), `memory_diagnose` (server health, crash history, recovery steps)
+
+## Knowledge Topics
+
+| Topic | Purpose | Global? | Expires? | Default Trust |
+|-------|---------|---------|----------|---------------|
+| `user` | Personal info (name, role, communication style) | Yes | Never | `user` |
+| `preferences` | Corrections, opinions, coding rules | Yes | Never | `user` |
+| `gotchas` | Pitfalls and known issues | No | Never | `user` |
+| `architecture` | System design, patterns, module structure | No | 30 days | `agent-inferred` |
+| `conventions` | Code style, naming, patterns | No | 30 days | `agent-inferred` |
+| `modules/<name>` | Per-module knowledge | No | 30 days | `agent-inferred` |
+| `recent-work` | Current task context (branch-scoped) | No | 30 days | `agent-inferred` |
+
+**Global topics** (`user`, `preferences`) are stored in a shared global store at `~/.memory-mcp/global/` and are accessible from all lobes. This means your identity and coding preferences follow you across every repository without duplication.
+
+### Smart Surfacing
+
+- **Dedup detection**: When you store an entry, the response shows similar existing entries in the same topic (>35% keyword overlap) with consolidation instructions
+- **Preference surfacing**: Storing a non-preference entry shows relevant preferences that might conflict
+- **Piggyback hints**: `memory_correct` suggests storing corrections as reusable preferences
+- **`memory_context`**: Describe your task in natural language and get ranked results across all topics with topic-based boosting (preferences 1.8x, gotchas 1.5x)
+
+### Smart Filter Syntax
+
+`memory_query` supports a filter mini-language for precise searches:
+
+| Syntax | Meaning | Example |
+|--------|---------|---------|
+| `A B` | AND (both required) | `reducer sealed` |
+| `A\|B` | OR (either matches) | `MVI\|MVVM` |
+| `-A` | NOT (exclude) | `-deprecated` |
+| combined | Mix freely | `kotlin sealed\|swift protocol -deprecated` |
+
+Filters use stemmed matching, so `reducers` matches `reducer` and `exceptions` matches `exception`.
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+```
+
+## Configuration
+
+### Config File (Recommended)
+
+Create a `memory-config.json` file next to the memory MCP server:
+
+```json
+{
+  "lobes": {
+    "workspace-mcp": {
+      "root": "$HOME/git/personal/workspace-mcp",
+      "budgetMB": 2
+    },
+    "workrail": {
+      "root": "$HOME/git/personal/workrail",
+      "budgetMB": 2
+    }
+  }
+}
+```
+
+> **Note:** `memoryDir` is optional. When omitted, storage auto-detects to `.git/memory/` for git repos.
+
+**What's a "lobe"?** Each repository gets its own memory lobe -- a dedicated knowledge scope. Think of it like brain regions: the "workrail lobe" stores knowledge about workrail, the "workspace-mcp lobe" stores knowledge about workspace-mcp.
+
+**Benefits:**
+- Portable (`$HOME` and `~` expansion works across machines)
+- Discoverable (use `memory_list_lobes` to see what's configured)
+- Easy to extend (just add a new lobe entry)
+
+### Environment Variables (Fallback)
+
+If no `memory-config.json` is found, the server falls back to environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MEMORY_MCP_WORKSPACES` | -- | JSON mapping workspace names to repo paths (multi-repo mode) |
+| `MEMORY_MCP_REPO_ROOT` | `process.cwd()` | Fallback: single-repo path (if `WORKSPACES` not set) |
+| `MEMORY_MCP_DIR` | *(auto-detect)* | Override storage dir (relative to repo root, or absolute). Disables git-native auto-detection. |
+| `MEMORY_MCP_BUDGET` | `2097152` (2MB) | Storage budget per workspace in bytes |
+
+### Adding a New Lobe
+
+1. **Edit `memory-config.json`** (create if it doesn't exist)
+2. **Add lobe entry:**
+   ```json
+   "my-project": {
+     "root": "$HOME/git/my-project",
+     "budgetMB": 2
+   }
+   ```
+3. **Restart the memory MCP server**
+4. **Verify:** Use `memory_list_lobes` to confirm it loaded
+
+The agent will see the new lobe in tool descriptions and can immediately use it with `memory_store(lobe: "my-project", ...)`.
+
+## MCP Client Registration
+
+With `memory-config.json` (recommended):
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "node",
+      "args": ["/path/to/memory-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+The server reads `memory-config.json` automatically -- no env vars needed.
+
+### Environment Variable Mode
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "node",
+      "args": ["/path/to/memory-mcp/dist/index.js"],
+      "env": {
+        "MEMORY_MCP_WORKSPACES": "{\"android\":\"/path/to/android\",\"ios\":\"/path/to/ios\"}"
+      }
+    }
+  }
+}
+```
+
+## Storage Location
+
+Knowledge is stored as human-readable Markdown files -- **one file per entry**. The storage location is **auto-detected** with the following priority:
+
+1. **Explicit `memoryDir` config** -- if set in `memory-config.json` or `MEMORY_MCP_DIR`, uses that path
+2. **Git-native** (default) -- `<git-common-dir>/memory/` using `git rev-parse --git-common-dir`. This ensures:
+   - **Invisible to git** -- `.git/` contents are never tracked, no `.gitignore` needed
+   - **Shared across worktrees** -- all worktrees of the same repo share one memory store
+   - **Worktree/submodule safe** -- resolves to the common `.git/` directory regardless
+3. **Central fallback** -- `~/.memory-mcp/<lobe-name>/` for non-git directories
+
+Use `memory_stats` or `memory_list_lobes` to see where memory is stored for each lobe.
+
+### File Structure
+
+Each entry gets its own file. Recent-work entries are scoped by branch.
+
+```
+.git/memory/
+  architecture/
+    arch-e8d4f012.md              # One entry per file
+  conventions/
+    conv-a1b2c3d4.md
+  gotchas/
+    gotcha-7k3m9p2q.md
+  recent-work/
+    main/                          # Branch-scoped
+      recent-f5e6d7c8.md
+    feature-messaging-refactor/    # Sanitized branch name
+      recent-9i0j1k2l.md
+  modules/
+    messaging/
+      mod-4d5e6f7g.md
+
+~/.memory-mcp/global/              # Global store (shared across all lobes)
+  user/
+    user-3f7a2b1c.md              # Personal info
+  preferences/
+    pref-5c9b7e3d.md              # Coding opinions & corrections
+```
+
+### Concurrency Safety
+
+Each entry is its own file with a random hex ID. Two MCP processes (e.g., Firebender + Cursor) writing different entries to the same repo **never conflict** -- they write to different files. The store reloads from disk before every read to pick up changes from other processes.
+
+### Branch-Scoped Recent Work
+
+Recent-work entries are automatically tagged with the current git branch and stored in a branch-named subdirectory. `memory_query` filters recent-work to the current branch by default. Use `branch: "*"` to see recent-work from all branches.
+
+### Entry Format
+
+```markdown
+# Build System & Language
+- **id**: arch-3f7a2b1c
+- **topic**: architecture
+- **confidence**: 0.70
+- **trust**: agent-inferred
+- **created**: 2026-02-18T12:00:00.000Z
+- **lastAccessed**: 2026-02-18T12:00:00.000Z
+
+Detected: Node.js/TypeScript project (npm)
+```
+
+## Trust Levels
+
+| Level | Confidence | Meaning |
+|-------|-----------|---------|
+| `user` | 1.0 | Human-provided or human-corrected knowledge |
+| `agent-confirmed` | 0.85 | Agent-observed and verified against code |
+| `agent-inferred` | 0.70 | Agent-observed, not yet verified |
+
+## Resilience
+
+The server uses a **degradation ladder** to stay useful even when things go wrong:
+
+- **Running** -- all lobes healthy, full functionality
+- **Degraded** -- some lobes failed to initialize but healthy ones continue working. Failed lobes report specific recovery steps via `memory_diagnose`.
+- **Safe Mode** -- all lobes failed. Only `memory_diagnose` and `memory_list_lobes` work, giving you enough information to fix the problem.
+
+**Crash journaling**: On uncaught exceptions, the server writes a structured crash report to `~/.memory-mcp/crashes/` before exiting. The next startup surfaces the crash in `memory_context()` (briefing mode) with recovery steps. Use `memory_diagnose(showCrashHistory: true)` to see the full history.
+
+### Argument Normalization
+
+Agents frequently guess wrong parameter names. The server silently resolves common aliases to avoid wasted round-trips:
+
+| Alias | Resolves to |
+|-------|-------------|
+| `key`, `name` | `title` |
+| `value`, `body`, `text` | `content` |
+| `query`, `search` | `filter` |
+| `workspace`, `repo` | `lobe` |
+
+Wildcard scope aliases (`all`, `everything`, `global`, `project`) resolve to `*`.
+
+## Architecture
+
+```
+types.ts          Domain types (discriminated unions, parse functions)
+store.ts          MarkdownMemoryStore (CRUD, search, bootstrap, briefing)
+text-analyzer.ts  Keyword extraction, stemming, similarity (stateless)
+normalize.ts      Argument alias resolution (pure)
+formatters.ts     Response formatters for tool handlers (pure)
+config.ts         3-tier config loading (file > env > default)
+git-service.ts    Git operations boundary (injectable for testing)
+crash-journal.ts  Crash report lifecycle (build, write, read, format)
+index.ts          MCP server, tool handlers, startup, migration
+```
+
+## Design
+
+See `ideas/codebase-memory-mcp-design-thinking.md` for the full design thinking document with 67 ideas, 5 concept packages, pre-mortem analysis, and test plan.

package/dist/__tests__/clock-and-validators.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/clock-and-validators.test.js

@@ -0,0 +1,237 @@
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import { MarkdownMemoryStore } from '../store.js';
+import { DEFAULT_STORAGE_BUDGET_BYTES, parseTopicScope, parseTrustLevel } from '../types.js';
+// --- Fake clock: deterministic time for testing staleness ---
+function fakeClock(isoDate) {
+    const date = new Date(isoDate);
+    return {
+        now: () => new Date(date.getTime()),
+        isoNow: () => date.toISOString(),
+    };
+}
+function makeConfig(repoRoot, clock) {
+    return {
+        repoRoot,
+        memoryPath: path.join(repoRoot, '.memory'),
+        storageBudgetBytes: DEFAULT_STORAGE_BUDGET_BYTES,
+        clock,
+    };
+}
+async function createTempDir() {
+    return await fs.mkdtemp(path.join(os.tmpdir(), 'memory-mcp-clock-test-'));
+}
+// --- parseTopicScope tests ---
+describe('parseTopicScope', () => {
+    it('accepts all fixed topics', () => {
+        const fixed = ['user', 'preferences', 'architecture', 'conventions', 'gotchas', 'recent-work'];
+        for (const topic of fixed) {
+            assert.strictEqual(parseTopicScope(topic), topic, `Should accept "${topic}"`);
+        }
+    });
+    it('accepts modules/ prefixed topics', () => {
+        assert.strictEqual(parseTopicScope('modules/messaging'), 'modules/messaging');
+        assert.strictEqual(parseTopicScope('modules/auth'), 'modules/auth');
+        assert.strictEqual(parseTopicScope('modules/deep/nested'), 'modules/deep/nested');
+    });
+    it('rejects empty string', () => {
+        assert.strictEqual(parseTopicScope(''), null);
+    });
+    it('rejects arbitrary strings', () => {
+        assert.strictEqual(parseTopicScope('banana'), null);
+        assert.strictEqual(parseTopicScope('foobar'), null);
+        assert.strictEqual(parseTopicScope('arch'), null);
+    });
+    it('rejects "modules/" without a name', () => {
+        assert.strictEqual(parseTopicScope('modules/'), null);
+    });
+    it('is case-sensitive', () => {
+        assert.strictEqual(parseTopicScope('Architecture'), null);
+        assert.strictEqual(parseTopicScope('USER'), null);
+    });
+});
+// --- parseTrustLevel tests ---
+describe('parseTrustLevel', () => {
+    it('accepts all valid trust levels', () => {
+        assert.strictEqual(parseTrustLevel('user'), 'user');
+        assert.strictEqual(parseTrustLevel('agent-confirmed'), 'agent-confirmed');
+        assert.strictEqual(parseTrustLevel('agent-inferred'), 'agent-inferred');
+    });
+    it('rejects arbitrary strings', () => {
+        assert.strictEqual(parseTrustLevel('admin'), null);
+        assert.strictEqual(parseTrustLevel(''), null);
+        assert.strictEqual(parseTrustLevel('USER'), null);
+    });
+});
+// --- Fake clock: staleness and freshness ---
+describe('Clock injection for freshness', () => {
+    let tempDir;
+    beforeEach(async () => {
+        tempDir = await createTempDir();
+    });
+    it('entries older than 30 days are stale with fake clock', async () => {
+        // Store entries with a clock set to Jan 1, 2025
+        const jan1 = fakeClock('2025-01-01T00:00:00.000Z');
+        const store1 = new MarkdownMemoryStore(makeConfig(tempDir, jan1));
+        await store1.init();
+        await store1.store('architecture', 'Old Pattern', 'This was stored long ago', [], 'agent-inferred');
+        // Query with a clock set to Mar 1, 2025 (59 days later — well past 30)
+        const mar1 = fakeClock('2025-03-01T00:00:00.000Z');
+        const store2 = new MarkdownMemoryStore(makeConfig(tempDir, mar1));
+        await store2.init();
+        const result = await store2.query('architecture', 'brief');
+        assert.strictEqual(result.entries.length, 1);
+        assert.strictEqual(result.entries[0].fresh, false, 'Entry should be stale after 59 days');
+    });
+    it('entries within 30 days are fresh with fake clock', async () => {
+        const jan1 = fakeClock('2025-01-01T00:00:00.000Z');
+        const store1 = new MarkdownMemoryStore(makeConfig(tempDir, jan1));
+        await store1.init();
+        await store1.store('architecture', 'Recent Pattern', 'Just stored', [], 'agent-inferred');
+        // Query 15 days later — still within 30
+        const jan16 = fakeClock('2025-01-16T00:00:00.000Z');
+        const store2 = new MarkdownMemoryStore(makeConfig(tempDir, jan16));
+        await store2.init();
+        const result = await store2.query('architecture', 'brief');
+        assert.strictEqual(result.entries.length, 1);
+        assert.strictEqual(result.entries[0].fresh, true, 'Entry should be fresh within 30 days');
+    });
+    it('user topic entries are always fresh regardless of age', async () => {
+        const jan1 = fakeClock('2025-01-01T00:00:00.000Z');
+        const store1 = new MarkdownMemoryStore(makeConfig(tempDir, jan1));
+        await store1.init();
+        await store1.store('user', 'Identity', 'An engineer', [], 'user');
+        // Query 1 year later — user topic is exempt
+        const nextYear = fakeClock('2026-01-01T00:00:00.000Z');
+        const store2 = new MarkdownMemoryStore(makeConfig(tempDir, nextYear));
+        await store2.init();
+        const result = await store2.query('user', 'brief');
+        assert.strictEqual(result.entries[0].fresh, true, 'User topic should always be fresh');
+    });
+    it('preferences entries are stale after 90 days, fresh before', async () => {
+        // Use separate temp dirs to prevent query() from refreshing lastAccessed between scenarios
+        const dir60 = await fs.mkdtemp(path.join(os.tmpdir(), 'mem-pref-60-'));
+        const dir100 = await fs.mkdtemp(path.join(os.tmpdir(), 'mem-pref-100-'));
+        try {
+            const jan1 = fakeClock('2025-01-01T00:00:00.000Z');
+            // Scenario 1: written Jan 1, queried Mar 2 (60 days) — should be fresh
+            const write60 = new MarkdownMemoryStore(makeConfig(dir60, jan1));
+            await write60.init();
+            await write60.store('preferences', 'Style', 'Functional first', [], 'user');
+            const mar2 = fakeClock('2025-03-02T00:00:00.000Z'); // ~60 days later
+            const read60 = new MarkdownMemoryStore(makeConfig(dir60, mar2));
+            await read60.init();
+            const result60 = await read60.query('preferences', 'brief');
+            assert.strictEqual(result60.entries[0].fresh, true, 'Preference at 60 days should still be fresh (within 90-day window)');
+            // Scenario 2: written Jan 1, queried Apr 11 (100 days) — should be stale
+            const write100 = new MarkdownMemoryStore(makeConfig(dir100, jan1));
+            await write100.init();
+            await write100.store('preferences', 'Style', 'Functional first', [], 'user');
+            const apr11 = fakeClock('2025-04-11T00:00:00.000Z'); // ~100 days later
+            const read100 = new MarkdownMemoryStore(makeConfig(dir100, apr11));
+            await read100.init();
+            const result100 = await read100.query('preferences', 'brief');
+            assert.strictEqual(result100.entries[0].fresh, false, 'Preference at 100 days should be stale (exceeds 90-day window)');
+        }
+        finally {
+            await fs.rm(dir60, { recursive: true, force: true }).catch(() => { });
+            await fs.rm(dir100, { recursive: true, force: true }).catch(() => { });
+        }
+    });
+    it('gotchas go stale after 30 days (not always-fresh)', async () => {
+        const jan1 = fakeClock('2025-01-01T00:00:00.000Z');
+        const store1 = new MarkdownMemoryStore(makeConfig(tempDir, jan1));
+        await store1.init();
+        await store1.store('gotchas', 'Build Gotcha', 'Always clean build', [], 'agent-inferred');
+        // Query 1 year later — gotchas are NOT exempt from staleness
+        const nextYear = fakeClock('2026-01-01T00:00:00.000Z');
+        const store2 = new MarkdownMemoryStore(makeConfig(tempDir, nextYear));
+        await store2.init();
+        const result = await store2.query('gotchas', 'brief');
+        assert.strictEqual(result.entries[0].fresh, false, 'Gotchas should go stale after 30 days — code changes make them the most dangerous when outdated');
+    });
+    it('user-trusted entries in non-user topics go stale normally (trust != temporal validity)', async () => {
+        const jan1 = fakeClock('2025-01-01T00:00:00.000Z');
+        const store1 = new MarkdownMemoryStore(makeConfig(tempDir, jan1));
+        await store1.init();
+        await store1.store('conventions', 'User Convention', 'User confirmed this', [], 'user');
+        // Query 1 year later — trust level does not grant freshness exemption
+        const nextYear = fakeClock('2026-01-01T00:00:00.000Z');
+        const store2 = new MarkdownMemoryStore(makeConfig(tempDir, nextYear));
+        await store2.init();
+        const result = await store2.query('conventions', 'brief');
+        assert.strictEqual(result.entries[0].fresh, false, 'Trust level does not grant freshness exemption — a user-confirmed entry can still be outdated');
+    });
+    it('stale count in briefing reflects tiered thresholds', async () => {
+        const jan1 = fakeClock('2025-01-01T00:00:00.000Z');
+        const store1 = new MarkdownMemoryStore(makeConfig(tempDir, jan1));
+        await store1.init();
+        await store1.store('architecture', 'Old Arch', 'content', [], 'agent-inferred');
+        await store1.store('conventions', 'Old Conv', 'content', [], 'agent-confirmed');
+        await store1.store('gotchas', 'Gotcha', 'content', [], 'agent-inferred'); // stale after 30 days
+        // Briefing 60 days later
+        const mar2 = fakeClock('2025-03-02T00:00:00.000Z');
+        const store2 = new MarkdownMemoryStore(makeConfig(tempDir, mar2));
+        await store2.init();
+        const briefing = await store2.briefing(2000);
+        // arch + conv + gotcha are all stale at 60 days (all use 30-day threshold)
+        assert.strictEqual(briefing.staleEntries, 3, 'arch, conv, and gotcha should all be stale at 60 days');
+    });
+    it('clock is used for created/lastAccessed timestamps', async () => {
+        const fixedTime = fakeClock('2025-06-15T12:30:00.000Z');
+        const store1 = new MarkdownMemoryStore(makeConfig(tempDir, fixedTime));
+        await store1.init();
+        await store1.store('architecture', 'Test Entry', 'content');
+        const result = await store1.query('architecture', 'full');
+        assert.strictEqual(result.entries[0].created, '2025-06-15T12:30:00.000Z');
+        assert.strictEqual(result.entries[0].lastAccessed, '2025-06-15T12:30:00.000Z');
+    });
+});
+// --- Confidence range validation ---
+describe('confidence clamping on disk read', () => {
+    let tempDir;
+    beforeEach(async () => {
+        tempDir = await createTempDir();
+    });
+    it('clamps out-of-range confidence to valid range on reload', async () => {
+        const store1 = new MarkdownMemoryStore(makeConfig(tempDir));
+        await store1.init();
+        // Manually write a file with confidence: 999
+        const dir = path.join(tempDir, '.memory', 'architecture');
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(path.join(dir, 'arch-bad1.md'), [
+            '# High Confidence',
+            '- **id**: arch-bad1',
+            '- **topic**: architecture',
+            '- **confidence**: 999',
+            '- **trust**: agent-inferred',
+            '- **created**: 2025-01-01T00:00:00.000Z',
+            '- **lastAccessed**: 2025-01-01T00:00:00.000Z',
+            '',
+            'This entry has absurd confidence.',
+        ].join('\n'));
+        // Manually write a file with confidence: -5
+        await fs.writeFile(path.join(dir, 'arch-bad2.md'), [
+            '# Negative Confidence',
+            '- **id**: arch-bad2',
+            '- **topic**: architecture',
+            '- **confidence**: -5',
+            '- **trust**: agent-inferred',
+            '- **created**: 2025-01-01T00:00:00.000Z',
+            '- **lastAccessed**: 2025-01-01T00:00:00.000Z',
+            '',
+            'This entry has negative confidence.',
+        ].join('\n'));
+        const store2 = new MarkdownMemoryStore(makeConfig(tempDir));
+        await store2.init();
+        const result = await store2.query('architecture', 'full');
+        assert.strictEqual(result.entries.length, 2);
+        for (const entry of result.entries) {
+            assert.ok(entry.confidence >= 0.0, `Confidence ${entry.confidence} should be >= 0.0`);
+            assert.ok(entry.confidence <= 1.0, `Confidence ${entry.confidence} should be <= 1.0`);
+        }
+    });
+});

package/dist/__tests__/config-manager.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/config-manager.test.js

@@ -0,0 +1,142 @@
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { ConfigManager } from '../config-manager.js';
+// Test helper: ConfigManager subclass with injectable stat function
+class TestableConfigManager extends ConfigManager {
+    constructor() {
+        super(...arguments);
+        this.statImplementation = async () => {
+            return { mtimeMs: Date.now() - 1000 };
+        };
+    }
+    statFile(path) {
+        return this.statImplementation(path);
+    }
+}
+describe('ConfigManager', () => {
+    let initialConfig;
+    let initialStores;
+    let initialHealth;
+    let configPath;
+    beforeEach(() => {
+        configPath = '/fake/memory-config.json';
+        // Mock initial config
+        const mockConfig = {
+            repoRoot: '/fake/repo',
+            memoryPath: '/fake/memory',
+            storageBudgetBytes: 2 * 1024 * 1024,
+        };
+        initialConfig = {
+            configs: new Map([['test-lobe', mockConfig]]),
+            origin: { source: 'file', path: configPath },
+        };
+        // Mock initial stores
+        const mockStore = {};
+        initialStores = new Map([['test-lobe', mockStore]]);
+        initialHealth = new Map([['test-lobe', { status: 'healthy' }]]);
+    });
+    describe('ensureFresh', () => {
+        it('does not reload when mtime unchanged', async () => {
+            const manager = new TestableConfigManager(configPath, initialConfig, initialStores, initialHealth);
+            let statCallCount = 0;
+            manager.statImplementation = async () => {
+                statCallCount++;
+                return { mtimeMs: Date.now() - 1000 }; // mtime in the past (no change)
+            };
+            await manager.ensureFresh();
+            await manager.ensureFresh();
+            // Stat should be called, but reload should not happen
+            assert.equal(statCallCount, 2, 'stat should be called twice');
+            assert.equal(manager.getLobeNames().length, 1, 'Should still have 1 lobe');
+        });
+        it('gracefully handles stat ENOENT error (file deleted)', async () => {
+            const manager = new TestableConfigManager(configPath, initialConfig, initialStores, initialHealth);
+            manager.statImplementation = async () => {
+                const error = new Error('ENOENT: no such file');
+                error.code = 'ENOENT';
+                throw error;
+            };
+            // Should not throw, should keep old config
+            await manager.ensureFresh();
+            assert.equal(manager.getLobeNames().length, 1, 'Should keep old config on ENOENT');
+        });
+        it('gracefully handles stat EACCES error (permission denied)', async () => {
+            const manager = new TestableConfigManager(configPath, initialConfig, initialStores, initialHealth);
+            manager.statImplementation = async () => {
+                const error = new Error('EACCES: permission denied');
+                error.code = 'EACCES';
+                throw error;
+            };
+            // Should not throw, should keep old config
+            await manager.ensureFresh();
+            assert.equal(manager.getLobeNames().length, 1, 'Should keep old config on EACCES');
+        });
+        it('skips reload for env-var-based configs', async () => {
+            const envConfig = {
+                configs: new Map([['test-lobe', initialConfig.configs.get('test-lobe')]]),
+                origin: { source: 'env' },
+            };
+            let statCalled = false;
+            const manager = new TestableConfigManager(configPath, envConfig, initialStores, initialHealth);
+            manager.statImplementation = async () => {
+                statCalled = true;
+                return { mtimeMs: Date.now() };
+            };
+            await manager.ensureFresh();
+            // stat should NOT be called for env-based configs
+            assert.equal(statCalled, false, 'Should not stat for env-based configs');
+        });
+        it('skips reload for default-based configs', async () => {
+            const defaultConfig = {
+                configs: new Map([['default', initialConfig.configs.get('test-lobe')]]),
+                origin: { source: 'default' },
+            };
+            let statCalled = false;
+            const manager = new TestableConfigManager(configPath, defaultConfig, initialStores, initialHealth);
+            manager.statImplementation = async () => {
+                statCalled = true;
+                return { mtimeMs: Date.now() };
+            };
+            await manager.ensureFresh();
+            // stat should NOT be called for default configs
+            assert.equal(statCalled, false, 'Should not stat for default configs');
+        });
+    });
+    describe('accessors', () => {
+        it('getStore returns store for existing lobe', () => {
+            const manager = new ConfigManager(configPath, initialConfig, initialStores, initialHealth);
+            const store = manager.getStore('test-lobe');
+            assert.ok(store !== undefined, 'Should return store for existing lobe');
+        });
+        it('getStore returns undefined for non-existent lobe', () => {
+            const manager = new ConfigManager(configPath, initialConfig, initialStores, initialHealth);
+            const store = manager.getStore('nonexistent');
+            assert.equal(store, undefined, 'Should return undefined for missing lobe');
+        });
+        it('getLobeNames returns array of lobe names', () => {
+            const manager = new ConfigManager(configPath, initialConfig, initialStores, initialHealth);
+            const names = manager.getLobeNames();
+            assert.deepEqual(names, ['test-lobe']);
+        });
+        it('getConfigOrigin returns current origin', () => {
+            const manager = new ConfigManager(configPath, initialConfig, initialStores, initialHealth);
+            const origin = manager.getConfigOrigin();
+            assert.equal(origin.source, 'file');
+            if (origin.source === 'file') {
+                assert.equal(origin.path, configPath);
+            }
+        });
+        it('getLobeHealth returns health for existing lobe', () => {
+            const manager = new ConfigManager(configPath, initialConfig, initialStores, initialHealth);
+            const health = manager.getLobeHealth('test-lobe');
+            assert.ok(health !== undefined);
+            assert.equal(health.status, 'healthy');
+        });
+        it('getLobeConfig returns config for existing lobe', () => {
+            const manager = new ConfigManager(configPath, initialConfig, initialStores, initialHealth);
+            const config = manager.getLobeConfig('test-lobe');
+            assert.ok(config !== undefined);
+            assert.equal(config.repoRoot, '/fake/repo');
+        });
+    });
+});

package/dist/__tests__/config.test.d.ts

@@ -0,0 +1 @@
+export {};