memory-journal-mcp 6.1.2 → 6.2.1

package/src/vector/vector-search-manager.ts

@@ -1,409 +0,0 @@
-/**
- * Memory Journal MCP Server - Vector Search Manager
- *
- * Semantic search using @huggingface/transformers for embeddings
- * and sqlite-vec for vector indexing (stored in the same SQLite database).
- */
-
-// @huggingface/transformers is loaded lazily via dynamic import() in initialize()
-// to avoid 1.5s cold-start penalty from eagerly loading the module.
-import type { Database as BetterSqlite3Database } from 'better-sqlite3'
-import { logger } from '../utils/logger.js'
-import type { IDatabaseAdapter } from '../database/core/interfaces.js'
-import type { JournalEntry } from '../types/index.js'
-import { sendProgress, type ProgressContext } from '../utils/progress-utils.js'
-import { ConfigurationError } from '../types/errors.js'
-
-/** Default model for embeddings (same as Python version) */
-const DEFAULT_MODEL = 'Xenova/all-MiniLM-L6-v2'
-
-/** Embedding dimensions for all-MiniLM-L6-v2 */
-const EMBEDDING_DIMENSIONS = 384
-
-/** Number of entries to embed concurrently during rebuild */
-const REBUILD_BATCH_SIZE = 5
-
-/** Number of entries to fetch per page during rebuild */
-const REBUILD_PAGE_SIZE = 200
-
-/** Search result with similarity score */
-export interface SemanticSearchResult {
-    entryId: number
-    score: number
-    entry?: JournalEntry
-}
-
-/**
- * VectorSearchManager - Handles semantic search with local embeddings
- *
- * Stores embeddings in the same SQLite database using the sqlite-vec extension.
- * Uses vec0 virtual tables for efficient KNN vector search via SQL.
- */
-export class VectorSearchManager {
-    // Use a more flexible type since FeatureExtractionPipeline doesn't fully implement Pipeline
-    private embedder:
-        | ((text: string, options?: Record<string, unknown>) => Promise<unknown>)
-        | null = null
-    private db: BetterSqlite3Database | null = null
-    private readonly modelName: string
-    private initialized = false
-    private initializing = false
-
-    constructor(
-        private readonly dbAdapter: IDatabaseAdapter,
-        modelName = DEFAULT_MODEL
-    ) {
-        this.modelName = modelName
-    }
-
-    /**
-     * Check if vector search is initialized
-     */
-    isInitialized(): boolean {
-        return this.initialized
-    }
-
-    /**
-     * Initialize the vector search manager (lazy loading)
-     */
-    async initialize(): Promise<void> {
-        if (this.initialized || this.initializing) return
-
-        this.initializing = true
-
-        try {
-            logger.info('Initializing vector search...', { module: 'VectorSearch' })
-
-            // Load embedding model (downloads on first use, ~23MB)
-            // Dynamic import avoids 1.5s cold-start penalty from eagerly loading the module
-            logger.info(`Loading embedding model: ${this.modelName}`, { module: 'VectorSearch' })
-            const { pipeline } = await import('@huggingface/transformers')
-            this.embedder = await pipeline('feature-extraction', this.modelName, {
-                dtype: 'q8', // Quantized int8 for faster inference and smaller model size
-            })
-            logger.info('Embedding model loaded', { module: 'VectorSearch' })
-
-            // Get the raw better-sqlite3 database instance
-            // sqlite-vec extension is already loaded by NativeConnectionManager
-            this.db = this.dbAdapter.getRawDb() as BetterSqlite3Database
-
-            this.initialized = true
-            this.initializing = false
-            logger.info('Vector search initialized successfully', { module: 'VectorSearch' })
-        } catch (error) {
-            this.initializing = false
-            logger.error('Failed to initialize vector search', {
-                module: 'VectorSearch',
-                error: error instanceof Error ? error.message : String(error),
-            })
-            throw error
-        }
-    }
-
-    /**
-     * Generate embedding for text
-     */
-    async generateEmbedding(text: string): Promise<number[]> {
-        if (!this.embedder) {
-            throw new ConfigurationError('Vector search not initialized')
-        }
-
-        // Generate embedding using feature-extraction pipeline
-        // The pipeline returns a Tensor with a data property containing the embeddings
-        const output = (await this.embedder(text, {
-            pooling: 'mean',
-            normalize: true,
-        })) as { data: ArrayLike<number> }
-
-        // Convert to number array
-        const embedding = Array.from(output.data)
-        return embedding
-    }
-
-    /**
-     * Add an entry to the vector index (upsert - replaces if exists)
-     */
-    async addEntry(
-        entryId: number,
-        content: string
-    ): Promise<{ success: boolean; error?: string }> {
-        if (!this.initialized) {
-            try {
-                await this.initialize()
-            } catch (initError) {
-                const msg = initError instanceof Error ? initError.message : String(initError)
-                return { success: false, error: `Vector search initialization failed: ${msg}` }
-            }
-        }
-
-        if (!this.db) {
-            return { success: false, error: 'Vector database not available' }
-        }
-
-        try {
-            // Generate embedding
-            const embedding = await this.generateEmbedding(content)
-
-            // vec0 virtual tables don't support INSERT OR REPLACE — use DELETE+INSERT
-            const vec = new Float32Array(embedding)
-            const bigId = BigInt(entryId)
-            // DELETE is a no-op if entry doesn't exist
-            this.db.prepare('DELETE FROM vec_embeddings WHERE entry_id = ?').run(bigId)
-            this.db
-                .prepare('INSERT INTO vec_embeddings(entry_id, embedding) VALUES (?, ?)')
-                .run(bigId, vec)
-
-            logger.debug('Added entry to vector index', {
-                module: 'VectorSearch',
-                entityId: entryId,
-            })
-
-            return { success: true }
-        } catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error)
-            logger.error('Failed to add entry to vector index', {
-                module: 'VectorSearch',
-                entityId: entryId,
-                error: errorMessage,
-            })
-            return { success: false, error: errorMessage }
-        }
-    }
-
-    /**
-     * Perform semantic search
-     *
-     * sqlite-vec returns L2 distance (lower = more similar).
-     * We convert to a similarity score: score = 1 / (1 + distance)
-     */
-    async search(
-        query: string,
-        limit = 10,
-        similarityThreshold = 0.3
-    ): Promise<SemanticSearchResult[]> {
-        if (!this.initialized) {
-            try {
-                await this.initialize()
-            } catch {
-                return []
-            }
-        }
-
-        if (!this.db) {
-            return []
-        }
-
-        try {
-            // Generate query embedding
-            const queryEmbedding = await this.generateEmbedding(query)
-            const queryVec = new Float32Array(queryEmbedding)
-
-            // KNN search via sqlite-vec vec0 virtual table
-            // Returns entry_id and distance (L2), ordered by distance ascending
-            const results = this.db
-                .prepare(
-                    `SELECT entry_id, distance
-                     FROM vec_embeddings
-                     WHERE embedding MATCH ?
-                     ORDER BY distance
-                     LIMIT ?`
-                )
-                .all(queryVec, limit * 2) as { entry_id: number; distance: number }[]
-
-            // Convert L2 distance to similarity score and filter by threshold
-            const filteredResults: SemanticSearchResult[] = results
-                .map((r) => ({
-                    entryId: r.entry_id,
-                    score: 1 / (1 + r.distance),
-                }))
-                .filter((r) => r.score >= similarityThreshold)
-                .slice(0, limit)
-
-            return filteredResults
-        } catch (error) {
-            logger.error('Semantic search failed', {
-                module: 'VectorSearch',
-                error: error instanceof Error ? error.message : String(error),
-            })
-            return []
-        }
-    }
-
-    /**
-     * Remove an entry from the vector index
-     */
-    removeEntry(entryId: number): boolean {
-        if (!this.db) return false
-
-        try {
-            // sqlite-vec vec0 requires BigInt primary keys through better-sqlite3 bindings
-            this.db.prepare('DELETE FROM vec_embeddings WHERE entry_id = ?').run(BigInt(entryId))
-            return true
-        } catch (error) {
-            logger.debug('Vector removeEntry failed (item may not exist)', {
-                module: 'VectorSearch',
-                entityId: entryId,
-                error: error instanceof Error ? error.message : String(error),
-            })
-            return false
-        }
-    }
-
-    /**
-     * Rebuild index from database entries.
-     * Uses paginated fetching and parallel batch embedding for performance.
-     * @param db - Database adapter
-     * @param progress - Optional progress context for notifications
-     */
-    async rebuildIndex(
-        db: IDatabaseAdapter,
-        progress?: ProgressContext
-    ): Promise<{ indexed: number; failed: number; firstError: string | null }> {
-        if (!this.initialized) {
-            try {
-                await this.initialize()
-            } catch (initError) {
-                const msg = initError instanceof Error ? initError.message : String(initError)
-                return {
-                    indexed: 0,
-                    failed: 0,
-                    firstError: `Vector search initialization failed: ${msg}`,
-                }
-            }
-        }
-
-        if (!this.db) {
-            return { indexed: 0, failed: 0, firstError: null }
-        }
-
-        logger.info('Rebuilding vector index from database...', { module: 'VectorSearch' })
-
-        // Step 1: Get total entry count for progress reporting
-        const totalEntries = db.getActiveEntryCount()
-
-        // Step 2: Clear existing embeddings (O(1) operation)
-        this.db.prepare('DELETE FROM vec_embeddings').run()
-        logger.info('Cleared vec_embeddings table for rebuild', { module: 'VectorSearch' })
-
-        // Step 3: Re-index all entries using paginated fetch
-        // Embeddings are generated in parallel batches (CPU-bound, safe),
-        // then inserted into SQLite (synchronous, fast, concurrency-safe via WAL)
-        await sendProgress(progress, 0, totalEntries, 'Starting vector index rebuild...')
-
-        // Prepare insert statement once for reuse
-        const insertStmt = this.db.prepare(
-            'INSERT INTO vec_embeddings(entry_id, embedding) VALUES (?, ?)'
-        )
-
-        let indexed = 0
-        let failed = 0
-        let firstError: string | null = null
-        for (let offset = 0; offset < totalEntries; offset += REBUILD_PAGE_SIZE) {
-            const page = db.getEntriesPage(offset, REBUILD_PAGE_SIZE)
-
-            // Generate embeddings in parallel batches
-            for (let i = 0; i < page.length; i += REBUILD_BATCH_SIZE) {
-                const batch = page.slice(i, i + REBUILD_BATCH_SIZE)
-
-                // Parallel embedding generation
-                const embeddings = await Promise.all(
-                    batch.map(async (entry: JournalEntry) => {
-                        try {
-                            return {
-                                entry,
-                                embedding: await this.generateEmbedding(entry.content),
-                                error: null,
-                            }
-                        } catch (embError) {
-                            const errorMsg =
-                                embError instanceof Error ? embError.message : String(embError)
-                            logger.debug('Failed to generate embedding for entry', {
-                                module: 'VectorSearch',
-                                entityId: entry.id,
-                                error: errorMsg,
-                            })
-                            return { entry, embedding: null as number[] | null, error: errorMsg }
-                        }
-                    })
-                )
-
-                // Insert embeddings into SQLite
-                for (const { entry, embedding, error: embError } of embeddings) {
-                    if (embedding !== null) {
-                        try {
-                            const vec = new Float32Array(embedding)
-                            // sqlite-vec vec0 requires BigInt primary keys through better-sqlite3 bindings
-                            insertStmt.run(BigInt(entry.id), vec)
-                            indexed++
-                        } catch (error) {
-                            failed++
-                            const errorMsg = error instanceof Error ? error.message : String(error)
-                            firstError ??= errorMsg
-                            logger.error('Failed to insert entry into vector index', {
-                                module: 'VectorSearch',
-                                entityId: entry.id,
-                                error: errorMsg,
-                            })
-                        }
-                    } else {
-                        failed++
-                        if (embError !== null) firstError ??= embError
-                    }
-                }
-
-                // Report progress every 10 entries to avoid flooding
-                if (indexed % 10 === 0 || indexed === totalEntries) {
-                    await sendProgress(
-                        progress,
-                        indexed,
-                        totalEntries,
-                        `Indexed ${String(indexed)} of ${String(totalEntries)} entries`
-                    )
-                }
-            }
-        }
-
-        // Final progress
-        await sendProgress(progress, indexed, totalEntries, 'Vector index rebuild complete')
-
-        if (failed > 0) {
-            logger.warning(
-                `Vector index rebuild: ${String(indexed)} indexed, ${String(failed)} failed`,
-                {
-                    module: 'VectorSearch',
-                }
-            )
-        } else {
-            logger.info(`Rebuilt vector index with ${String(indexed)} entries`, {
-                module: 'VectorSearch',
-            })
-        }
-        return { indexed, failed, firstError }
-    }
-
-    /**
-     * Get index statistics
-     */
-    getStats(): { itemCount: number; modelName: string; dimensions: number } {
-        if (!this.db) {
-            return { itemCount: 0, modelName: this.modelName, dimensions: EMBEDDING_DIMENSIONS }
-        }
-
-        try {
-            const result = this.db.prepare('SELECT COUNT(*) as count FROM vec_embeddings').get() as
-                | { count: number }
-                | undefined
-            return {
-                itemCount: result?.count ?? 0,
-                modelName: this.modelName,
-                dimensions: EMBEDDING_DIMENSIONS,
-            }
-        } catch (error) {
-            logger.debug('Failed to get vector index stats', {
-                module: 'VectorSearch',
-                error: error instanceof Error ? error.message : String(error),
-            })
-            return { itemCount: 0, modelName: this.modelName, dimensions: EMBEDDING_DIMENSIONS }
-        }
-    }
-}

package/src/version.ts

@@ -1,15 +0,0 @@
-/**
- * Version SSoT — Single Source of Truth
- *
- * Reads the version from package.json at runtime via createRequire.
- * All modules that need the version string should import from here
- * instead of importing package.json directly.
- */
-
-import { createRequire } from 'node:module'
-
-const require = createRequire(import.meta.url)
-const pkg = require('../package.json') as { version: string }
-
-/** The current server version, read from package.json */
-export const VERSION: string = pkg.version

package/test-server/README.md

@@ -1,193 +0,0 @@
-# Memory Journal MCP Test Server — Agent Testing Instructions
-
-> **This README is optimized for AI agent consumption.** It serves as the primary orchestration document for running manual MCP functionality tests against the `memory-journal-mcp` service. Test `.db` files in this directory are `.gitignore`d.
-
-## Files
-
-| File                      | Purpose                                                                                                                                                                               | When to Read           |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
-| `test-tools.md`           | **Pass 1: Core Functionality** — Phases 0-8, 10 covering seed data, happy paths, error paths, and feature verification for 41 core tools, 24 resources, 16 prompts, and scheduler     | Always read first      |
-| `test-tools-team.md`      | **Pass 1b: Team Collaboration** — Phase 9 covering 20 team tools + 2 team resources                                                                                                   | After Pass 1 completes |
-| `test-tools2.md`          | **Pass 2: Validation & Edge Cases** — Phases 11-15 covering outputSchema validation, structured error verification, data integrity, boundary values, and implementation bug detection | After Pass 1 completes |
-| `test-tools-codemode.md`  | **Pass 3: Code Mode** — Phases 16-21 covering sandbox execution, API discoverability, multi-step workflows, readonly mode, error handling, and cross-group orchestration              | After Pass 1 completes |
-| `test-tools-codemode2.md` | **Pass 4: Code Mode Advanced** — Extended Code Mode scenarios                                                                                                                         | After Pass 3 completes |
-
-| `test-preflight.md` | **Pre-flight check** — validates tiered instructions, resources, and tool-filter alignment in 5 steps | Before any test pass |
-| `test-agent-experience.md` | **Agent experience test** — 23 open-ended scenarios across 4 passes validating instruction sufficiency for cold-start | After instruction changes |
-| [`tool-reference.md`](tool-reference.md) | **Tool Reference** — Categorized list of all 61 tools across 11 groups | Reference |
-| [`code-map.md`](code-map.md) | **Source Code Map** — Directory tree, handler→tool mapping, type locations, error hierarchy, key constants, architecture patterns | When debugging source code or making changes |
-
-## Integration Test Scripts
-
-These scripts test features that require separate server processes — they **cannot** be run via MCP tool calls. All scripts are Node.js (`.mjs`), require no dependencies beyond Node.js, and exit with code 0 on success.
-
-> [!IMPORTANT]
-> Always `npm run build` before running these scripts — they execute `dist/cli.js` directly.
-
-### Script Reference
-
-| Script                         | Tests                                                                                                                                 | Transport     | Duration |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -------- |
-| `test-instruction-levels.mjs`  | `--instruction-level` essential/standard/full token ordering                                                                          | stdio         | ~10s     |
-| `test-filter-instructions.mjs` | Filter-aware sections — validates each `--tool-filter` config includes/excludes correct sections + reports token estimates per filter | stdio         | ~90s     |
-| `test-tool-annotations.mjs`    | `tools/list` openWorldHint annotation counts (45 false + 16 true = 61)                                                                | stdio         | ~5s      |
-| `test-prompts.mjs`             | `prompts/list` + `prompts/get` for all 16 prompts (shape + errors)                                                                    | stdio         | ~10s     |
-| `test-scheduler.mjs`           | Scheduler job execution (backup, vacuum, rebuild-index)                                                                               | HTTP stateful | ~130s    |
-
-### Quick Run
-
-```powershell
-cd C:\Users\chris\Desktop\memory-journal-mcp
-npm run build
-
-# Phase 1.3A — Instruction levels
-node test-server/test-instruction-levels.mjs
-
-# Phase 1.3B — Filter-aware instruction sections + token estimates
-node test-server/test-filter-instructions.mjs
-
-# Phase 1.3C — Tool annotations
-node test-server/test-tool-annotations.mjs
-
-# Phase 8 — Prompt handlers
-node test-server/test-prompts.mjs
-
-# Phase 9 — Scheduler (requires HTTP server in a separate terminal)
-node dist/cli.js --transport http --port 3099 --backup-interval 1 --keep-backups 3 --vacuum-interval 2 --rebuild-index-interval 2
-# In another terminal:
-node test-server/test-scheduler.mjs
-```
-
-### Scheduler Script Options
-
-| Env Variable   | Default                     | Description                                                          |
-| -------------- | --------------------------- | -------------------------------------------------------------------- |
-| `MCP_URL`      | `http://localhost:3099/mcp` | HTTP endpoint URL                                                    |
-| `WAIT_SECONDS` | `130`                       | Seconds to wait for jobs to fire (set to `0` for initial check only) |
-
-### Dual Transport Notes
-
-The server supports three transport modes:
-
-| Mode           | CLI Flags                      | Scheduler   | Sessions                 |
-| -------------- | ------------------------------ | ----------- | ------------------------ |
-| stdio          | `--transport stdio` (default)  | ❌ Inactive | N/A                      |
-| HTTP stateful  | `--transport http`             | ✅ Active   | `mcp-session-id` header  |
-| HTTP stateless | `--transport http --stateless` | ✅ Active   | No sessions (serverless) |
-
-The scheduler activates in **both** HTTP modes. The test script handles SSE response parsing automatically (HTTP transport returns `text/event-stream`). In stateless mode, there are no sessions so each request is independent — the scheduler still runs but session-scoped resources behave differently.
-
-## Success Criteria
-
-### Instruction Levels (Phase 1.3A)
-
-- [ ] essential (~1.2K tokens) < standard (~1.4K) < full (~6.7K)
-- [ ] No runtime errors in server logs
-
-### Filter-Aware Instructions (Phase 1.3B)
-
-- [ ] 9/9 filter configs pass section presence/absence checks
-- [ ] `full` includes CORE + COPILOT + CODE_MODE + GITHUB_INTEGRATION + SEARCH_ROW (~1790 tokens)
-- [ ] `codemode` omits COPILOT + GITHUB_INTEGRATION + SEARCH_ROW (~1190 tokens)
-- [ ] `essential` — CORE + CODE_MODE only (~1214 tokens)
-- [ ] `starter` — CORE + CODE_MODE + SEARCH_ROW (~1250 tokens)
-- [ ] `core` — CORE only (~759 tokens)
-- [ ] `full -codemode` — COPILOT + GITHUB_INTEGRATION + SEARCH_ROW, no CODE_MODE (~1147 tokens)
-- [ ] `full -github` — CODE_MODE + SEARCH_ROW, no COPILOT/GITHUB_INTEGRATION (~1391 tokens)
-- [ ] `readonly` — CORE + SEARCH_ROW, no CODE_MODE/COPILOT/GITHUB_INTEGRATION (~771 tokens)
-- [ ] `full --instruction-level essential` — omits GITHUB_INTEGRATION but keeps COPILOT + CODE_MODE (~1582 tokens)
-
-### Tool Annotations (Phase 1.3C)
-
-- [ ] 61 tools returned, all with `annotations` object
-- [ ] 45 tools with `openWorldHint: false`, 16 with `openWorldHint: true`, 0 missing
-
-### Scheduler (Phase 9)
-
-- [ ] `memory://health` shows `scheduler.active: false` and empty `jobs` array in stdio mode
-- [ ] Server logs confirm scheduler started with correct intervals
-- [ ] `memory://health` shows all 3 jobs active with `nextRun` timestamps
-- [ ] Backup job creates timestamped `.db` files and prunes to `--keep-backups` limit
-- [ ] Vacuum job logs `PRAGMA optimize` completion
-- [ ] Rebuild-index job logs vector index rebuild with entry count
-- [ ] All `lastResult` values are `"success"` after jobs fire
-- [ ] `lastError` remains `null` for all jobs
-- [ ] Error in one job does not prevent others from running
-
-## Conventions & Protocols
-
-| Convention                    | Rule                                                                                                                 |
-| ----------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| **Reporting**                 | ❌ Fail, ⚠️ Issue, 📦 Payload. ✅ inline only, omit from final summary.                                              |
-| **Error testing**             | Must return `{success: false, error: "...", code, category, suggestion, recoverable}`, NOT raw MCP error exceptions. |
-| **Error items in checklists** | Marked with 🔴 prefix                                                                                                |
-| **Post-test**                 | Clean up test databases/data → plan fixes → implement → lint+typecheck → changelog → commit (no push)                |
-
-## Connection Details & Portability
-
-The SQLite database path for `memory-journal-mcp` is entirely portable and **does not require code changes**.
-
-The server initializes its database locations using **Smart Path Resolution**:
-
-1. If `--db` or `DB_PATH` is passed explicitly, it is used immediately.
-2. If `memory_journal.db` exists in the root directory, it is used.
-3. If `test-server/test-memory-journal.db` exists, it falls back to this test database automatically.
-4. If neither exist, it creates a new `memory_journal.db` in the root.
-
-_(The identical fallback pattern applies to `--team-db` / `TEAM_DB_PATH` / `test-team-journal.db`)_.
-
-### Automated Test Artifacts
-
-When you run automated testing (e.g., `npm run test:e2e` or `vitest`), the test suites generate isolated database artifacts into the `.test-output/` directory (gitignored):
-
-- `.test-output/e2e/test-e2e.db`
-- `.test-output/e2e/test-e2e-auth.db`
-- `.test-output/e2e/test-e2e-stateless.db`
-- `.test-output/e2e/test-isolation-dir/`
-
-**You do NOT need to maintain a copy of your real journal database here.** The test prompts and automated suites are designed for "from-scratch" database workflows.
-
-## Agent Workflow
-
-1. Read the server instructions you received during initialization, then `memory://briefing`.
-2. Read `test-tools.md` for Pass 1 protocol, phases, and success criteria.
-3. Execute via direct MCP tool calls. Run both happy-path and 🔴 error-path tests.
-4. **Run integration test scripts** for Phase 1.3 (instruction levels, annotations), Phase 8 (prompts), and Phase 9 (scheduler).
-5. Provide manual cleanup (e.g., deleting test nodes) if testing stateful behavior.
-6. Report findings returning proper handler formatting.
-7. (Optional) Run Pass 1b from `test-tools-team.md` for team collaboration testing.
-8. (Optional) Run Pass 2 from `test-tools2.md` after Pass 1 completes successfully.
-9. (Optional) Run Pass 3 from `test-tools-codemode.md` for Code Mode sandbox testing.
-10. (Optional) Run Pass 4 from `test-tools-codemode2.md` for advanced Code Mode scenarios.
-
-## Troubleshooting
-
-### SQLite database locked
-
-The `memory-journal-mcp` uses `better-sqlite3` (native SQLite) in WAL mode. Lock errors are uncommon but can occur if multiple processes access the same `.db` file:
-
-1. Stop all MCP server instances accessing the database
-2. Delete any `*.db-journal` or `*.db-wal` files alongside the database
-3. Restart a single server instance
-
-### GitHub tools return "Could not auto-detect repository"
-
-1. Verify `GITHUB_REPO_PATH` is set in `mcp_config.json` env
-2. Verify the path points to a directory with a `.git` folder and a valid `origin` remote
-3. Alternatively, pass `owner` and `repo` parameters explicitly in tool calls
-
-### GitHub tools return 401/403
-
-1. Verify `GITHUB_TOKEN` is set and not expired
-2. Required scopes: `repo`, `project`, `read:org` (for org-level project discovery)
-3. For traffic/insights data, the token needs push access to the repository
-
-### Vector search returns no results
-
-1. Run `rebuild_vector_index` to re-index all entries
-2. Check `get_vector_index_stats` — if `itemCount: 0`, the index is empty
-3. The first index build triggers ML model download (~30MB) — verify network access
-
-### Team tools return "Team database not configured"
-
-Set `TEAM_DB_PATH` in `mcp_config.json` env or via `--team-db` CLI flag. The path can be any writable location.