persisted-memory 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 saharat
+
+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,281 @@
+# Persisted Memory for Claude Code
+
+A persistent memory system that survives Claude Code's context compaction. Memories are stored as **Markdown files** (source of truth) and indexed in **LanceDB** (vector search). Uses **Ollama** for local embeddings and AI-powered summarization with graceful degradation to keyword-only search.
+
+## How It Works
+
+```
+Claude Code Session (any project)
+  │
+  ├─ Hooks capture context automatically
+  │   SessionStart  → injects SUMMARY.md
+  │   PreCompact    → saves context before compaction
+  │   PostToolUse   → logs file changes
+  │   Stop          → marks turn completion
+  │   SessionEnd    → archives session + AI summary
+  │
+  └─ MCP Server provides 10 tools
+      memory_store, memory_search, memory_recall,
+      memory_list, memory_status, memory_forget,
+      memory_consolidate, memory_graph, memory_viewer
+```
+
+Memories are stored **per-project** at `<project>/.claude/memory/`. The MCP server and hooks are installed **once globally** and work with any project in any language.
+
+## Features
+
+- **Dual-write architecture** -- Markdown (human-readable, git-friendly) + LanceDB (fast vector search)
+- **Hybrid search** -- 70% semantic + 30% keyword, with automatic fallback
+- **Knowledge graph** -- automatic entity/relationship extraction across memories
+- **Progressive disclosure** -- token-efficient recall with summary/detailed/ids_only modes
+- **Privacy tags** -- wrap sensitive content in `<private>...</private>` to exclude from outputs
+- **AI-powered summaries** -- Ollama-generated session summaries (falls back to rule-based)
+- **Web viewer** -- browser-based UI for exploring and searching memories
+- **Zero external APIs** -- everything runs locally with Ollama
+
+## Prerequisites
+
+- **Node.js** 20+ (LTS)
+- **Ollama** with `nomic-embed-text` model (optional -- falls back to keyword search)
+
+```bash
+# Install Ollama (if not already installed)
+brew install ollama
+
+# Pull the embedding model
+ollama pull nomic-embed-text
+
+# Optional: pull the summarization model
+ollama pull llama3.2
+```
+
+## Installation
+
+### From npm
+
+```bash
+npm install -g persisted-memory
+```
+
+### From source
+
+```bash
+git clone <this-repo> ~/Works/persisted_memory
+cd ~/Works/persisted_memory
+npm install && npm run build
+bash scripts/install.sh
+```
+
+The install script will:
+1. Install dependencies and build
+2. Register the MCP server at user-level (`claude mcp add`)
+3. Register hooks in `~/.claude/settings.json`
+4. Add memory instructions to `~/.claude/CLAUDE.md`
+
+**Restart Claude Code** after installation.
+
+## Verification
+
+After restarting Claude Code:
+
+```
+# Check MCP server is connected
+/mcp
+
+# Check system status (inside any Claude Code session)
+Ask: "Check memory status"
+→ Claude calls memory_status → shows total entries, Ollama status, memory dir
+```
+
+## Usage
+
+### Automatic (via hooks)
+
+Hooks fire automatically during every Claude Code session:
+- **Session start**: Previous session's SUMMARY.md is injected into context
+- **File changes**: Edit/Write operations are logged to daily Markdown
+- **Context compaction**: Transcript is saved before compaction occurs
+- **Session end**: AI-powered summary is generated (or rule-based fallback)
+
+### Manual (via MCP tools)
+
+Ask Claude to use these tools naturally:
+
+| What you say | Tool called |
+|---|---|
+| "Remember that we use Yarn, not npm" | `memory_store` |
+| "What did we decide about authentication?" | `memory_search` |
+| "Recall everything about the database schema" | `memory_recall` |
+| "Show me all stored memories" | `memory_list` |
+| "Check memory system status" | `memory_status` |
+| "Forget memory abc-123" | `memory_forget` |
+| "Clean up duplicate memories" | `memory_consolidate` |
+| "What concepts are related to Docker?" | `memory_graph` |
+| "Open the memory viewer" | `memory_viewer` |
+
+### Privacy Tags
+
+Wrap sensitive content in `<private>` tags to keep it out of summaries, public views, and the web viewer:
+
+```
+memory_store: "API key is <private>sk-abc123</private>, use it for auth"
+```
+
+The private content is stored in LanceDB for search but stripped from all outputs. Tags are case-insensitive.
+
+### Progressive Disclosure
+
+The `memory_recall` tool supports three detail levels to optimize token usage:
+
+| Level | Description |
+|---|---|
+| `summary` (default) | Truncated text (200 chars), most token-efficient |
+| `detailed` | Full text of each memory |
+| `ids_only` | Just IDs, types, and scores -- minimal tokens |
+
+### Knowledge Graph
+
+Every stored memory automatically extracts entities (files, technologies, concepts) and creates relationships between them. Explore the graph:
+
+```
+"What entities are related to TypeScript?"  → memory_graph entity: "typescript"
+"Show me all known entities"                → memory_graph list_entities: true
+"How big is the knowledge graph?"           → memory_graph (default)
+```
+
+### Web Viewer
+
+Launch a browser-based memory explorer:
+
+```
+"Open the memory viewer" → memory_viewer
+```
+
+Or from the command line:
+```bash
+npm run viewer
+# Opens at http://localhost:3777
+```
+
+Features: dark theme, search with debounce, type/importance filter chips, expandable cards, pagination.
+
+### Memory Types
+
+When storing memories, specify a type:
+
+| Type | Use for |
+|---|---|
+| `decision` | Architecture/design decisions |
+| `architecture` | System design notes |
+| `code_change` | File modifications |
+| `error_fix` | Problem + solution pairs |
+| `pattern` | Reusable code patterns |
+| `context` | General session context |
+| `preference` | User/project preferences |
+
+### Importance Levels
+
+| Level | Use for |
+|---|---|
+| `critical` | Must never be forgotten |
+| `high` | Important decisions and patterns |
+| `medium` | Useful context (default) |
+| `low` | Minor notes |
+
+## Per-Project Data
+
+Each project gets its own memory directory:
+
+```
+<your-project>/.claude/memory/
+├── .lance/                # LanceDB vector index (add to .gitignore)
+├── SUMMARY.md             # Auto-generated context summary
+├── knowledge-graph.json   # Entity/relationship graph
+├── daily/                 # Daily session logs
+│   └── 2026-02-17.md
+├── sessions/              # Archived session summaries
+│   └── 2026-02-17-10-30.md
+└── decisions.md           # Append-only decisions log
+```
+
+Add to your project's `.gitignore`:
+```
+.claude/memory/.lance/
+```
+
+The `.md` and `.json` files are optionally committable -- they provide shareable context for team members.
+
+## Search
+
+Search uses a **hybrid approach**:
+- **70% semantic** (vector cosine similarity via Ollama embeddings)
+- **30% keyword** (LanceDB full-text search)
+
+If Ollama is unavailable, search falls back to **100% keyword** automatically.
+
+## Disaster Recovery
+
+Markdown files are the source of truth. If LanceDB data corrupts:
+
+1. Delete `.claude/memory/.lance/`
+2. The index will be rebuilt from Markdown on next use
+
+## Uninstallation
+
+```bash
+bash ~/Works/persisted_memory/scripts/uninstall.sh
+```
+
+This removes the MCP server and hooks. Per-project memory data at `<project>/.claude/memory/` is **preserved** -- delete manually if no longer needed.
+
+## Project Structure
+
+```
+persisted-memory/
+├── src/
+│   ├── index.ts                # Entry point (stdio MCP transport)
+│   ├── server.ts               # MCP server with 10 tool definitions
+│   ├── storage/
+│   │   ├── types.ts            # MemoryEntry, MemoryType, Importance
+│   │   ├── lance-store.ts      # LanceDB CRUD + vector/FTS search
+│   │   ├── markdown-store.ts   # Markdown file read/write/append
+│   │   └── knowledge-graph.ts  # Entity/relationship extraction + graph
+│   ├── embeddings/
+│   │   └── ollama.ts           # Ollama nomic-embed-text client
+│   ├── search/
+│   │   └── hybrid.ts           # Merge vector + keyword results
+│   ├── utils/
+│   │   ├── chunking.ts         # Split text into embeddable chunks
+│   │   ├── project.ts          # Resolve CLAUDE_PROJECT_DIR
+│   │   ├── privacy.ts          # Private tag stripping
+│   │   └── summarize.ts        # AI-powered summary generation
+│   ├── cli/
+│   │   ├── viewer.ts           # Web viewer CLI entry point
+│   │   └── generate-summary.ts # Summary generation CLI
+│   └── viewer/
+│       ├── server.ts           # HTTP server for web viewer
+│       └── index.html          # Self-contained web UI
+├── hooks/                      # Shell scripts for Claude Code hooks
+├── scripts/
+│   ├── install.sh              # Build + register MCP + hooks
+│   └── uninstall.sh            # Clean removal
+├── package.json
+└── tsconfig.json
+```
+
+## Dependencies
+
+Only 4 runtime packages:
+
+| Package | Purpose |
+|---|---|
+| `@modelcontextprotocol/sdk` | MCP server protocol |
+| `@lancedb/lancedb` | Embedded vector database |
+| `apache-arrow` | Columnar data format (LanceDB dep) |
+| `zod` | Schema validation for tool parameters |
+
+No Python. No Docker. No background daemons. No external APIs.
+
+## License
+
+MIT

package/dist/cli/generate-summary.d.ts

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

package/dist/cli/generate-summary.js

@@ -0,0 +1,13 @@
+import { generateSummary } from "../utils/summarize.js";
+import { getMemoryDir } from "../utils/project.js";
+import { writeSummary } from "../storage/markdown-store.js";
+async function main() {
+    const memoryDir = process.env.MEMORY_DIR || getMemoryDir();
+    const summary = await generateSummary(memoryDir);
+    writeSummary(memoryDir, summary);
+}
+main().catch((err) => {
+    console.error("Failed to generate summary:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=generate-summary.js.map

package/dist/cli/generate-summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-summary.js","sourceRoot":"","sources":["../../src/cli/generate-summary.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAE5D,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,YAAY,EAAE,CAAC;IAC3D,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,SAAS,CAAC,CAAC;IACjD,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;AACnC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,GAAG,CAAC,CAAC;IAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/cli/viewer.d.ts

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

package/dist/cli/viewer.js

@@ -0,0 +1,4 @@
+import { startViewer } from "../viewer/server.js";
+const port = parseInt(process.env.PORT || "3777", 10);
+startViewer(port);
+//# sourceMappingURL=viewer.js.map

package/dist/cli/viewer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewer.js","sourceRoot":"","sources":["../../src/cli/viewer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,MAAM,EAAE,EAAE,CAAC,CAAC;AACtD,WAAW,CAAC,IAAI,CAAC,CAAC"}

package/dist/embeddings/ollama.d.ts

@@ -0,0 +1,3 @@
+export declare function embed(text: string): Promise<number[] | null>;
+export declare function embedBatch(texts: string[]): Promise<(number[] | null)[]>;
+export declare function isAvailable(): Promise<boolean>;

package/dist/embeddings/ollama.js

@@ -0,0 +1,63 @@
+const OLLAMA_URL = process.env.OLLAMA_URL || "http://localhost:11434";
+const MODEL = "nomic-embed-text";
+const TIMEOUT_MS = 10_000;
+const HEALTH_TIMEOUT_MS = 3_000;
+export async function embed(text) {
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+        const res = await fetch(`${OLLAMA_URL}/api/embed`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ model: MODEL, input: text }),
+            signal: controller.signal,
+        });
+        clearTimeout(timer);
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return data.embeddings?.[0] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function embedBatch(texts) {
+    if (texts.length === 0)
+        return [];
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), TIMEOUT_MS * 2);
+        const res = await fetch(`${OLLAMA_URL}/api/embed`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ model: MODEL, input: texts }),
+            signal: controller.signal,
+        });
+        clearTimeout(timer);
+        if (!res.ok)
+            return texts.map(() => null);
+        const data = (await res.json());
+        if (!data.embeddings)
+            return texts.map(() => null);
+        return texts.map((_, i) => data.embeddings[i] ?? null);
+    }
+    catch {
+        return texts.map(() => null);
+    }
+}
+export async function isAvailable() {
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), HEALTH_TIMEOUT_MS);
+        const res = await fetch(`${OLLAMA_URL}/api/tags`, {
+            signal: controller.signal,
+        });
+        clearTimeout(timer);
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=ollama.js.map

package/dist/embeddings/ollama.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ollama.js","sourceRoot":"","sources":["../../src/embeddings/ollama.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,wBAAwB,CAAC;AACtE,MAAM,KAAK,GAAG,kBAAkB,CAAC;AACjC,MAAM,UAAU,GAAG,MAAM,CAAC;AAC1B,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEhC,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,IAAY;IACtC,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,UAAU,CAAC,CAAC;QAE/D,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,UAAU,YAAY,EAAE;YACjD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;YACnD,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;QAEH,YAAY,CAAC,KAAK,CAAC,CAAC;QAEpB,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QAEzB,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAgC,CAAC;QAC/D,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,KAAe;IAEf,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAElC,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,UAAU,GAAG,CAAC,CAAC,CAAC;QAEnE,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,UAAU,YAAY,EAAE;YACjD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;YACpD,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;QAEH,YAAY,CAAC,KAAK,CAAC,CAAC;QAEpB,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QAE1C,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAgC,CAAC;QAC/D,IAAI,CAAC,IAAI,CAAC,UAAU;YAAE,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QAEnD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,UAAW,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,iBAAiB,CAAC,CAAC;QAEtE,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,UAAU,WAAW,EAAE;YAChD,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;QAEH,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,OAAO,GAAG,CAAC,EAAE,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Graceful shutdown
+    const shutdown = async () => {
+        try {
+            await server.close();
+        }
+        catch {
+            // Ignore errors during shutdown
+        }
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+main().catch((err) => {
+    console.error("Failed to start memory server:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAE7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,oBAAoB;IACpB,MAAM,QAAQ,GAAG,KAAK,IAAI,EAAE;QAC1B,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,gCAAgC;QAClC,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IAEF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC/B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,gCAAgC,EAAE,GAAG,CAAC,CAAC;IACrD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/search/hybrid.d.ts

@@ -0,0 +1,8 @@
+import type { MemoryEntry, MemoryType, Importance } from "../storage/types.js";
+export interface SearchResult extends MemoryEntry {
+    score: number;
+}
+export declare function hybridSearch(query: string, limit?: number, filters?: {
+    type?: MemoryType;
+    importance?: Importance;
+}): Promise<SearchResult[]>;

package/dist/search/hybrid.js

@@ -0,0 +1,54 @@
+import * as lanceStore from "../storage/lance-store.js";
+import { embed, isAvailable } from "../embeddings/ollama.js";
+const VECTOR_WEIGHT = 0.7;
+const KEYWORD_WEIGHT = 0.3;
+export async function hybridSearch(query, limit = 10, filters) {
+    const ollamaUp = await isAvailable();
+    if (!ollamaUp) {
+        // Fallback: keyword-only search
+        return lanceStore.fullTextSearch(query, limit);
+    }
+    const queryVector = await embed(query);
+    if (!queryVector) {
+        // Embedding failed, fallback to keyword
+        return lanceStore.fullTextSearch(query, limit);
+    }
+    // Run both searches in parallel
+    const [vectorResults, keywordResults] = await Promise.all([
+        lanceStore.vectorSearch(queryVector, limit * 2, filters),
+        lanceStore.fullTextSearch(query, limit * 2),
+    ]);
+    // Merge results by ID
+    const merged = new Map();
+    for (const result of vectorResults) {
+        const existing = merged.get(result.id);
+        const vectorScore = result.score * VECTOR_WEIGHT;
+        if (existing) {
+            existing.score += vectorScore;
+        }
+        else {
+            merged.set(result.id, { ...result, score: vectorScore });
+        }
+    }
+    for (const result of keywordResults) {
+        const existing = merged.get(result.id);
+        const keywordScore = result.score * KEYWORD_WEIGHT;
+        if (existing) {
+            existing.score += keywordScore;
+        }
+        else {
+            merged.set(result.id, { ...result, score: keywordScore });
+        }
+    }
+    // Apply type/importance filters to keyword-only results
+    let results = Array.from(merged.values());
+    if (filters?.type) {
+        results = results.filter((r) => r.type === filters.type);
+    }
+    if (filters?.importance) {
+        results = results.filter((r) => r.importance === filters.importance);
+    }
+    // Sort by score descending, return top N
+    return results.sort((a, b) => b.score - a.score).slice(0, limit);
+}
+//# sourceMappingURL=hybrid.js.map

package/dist/search/hybrid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid.js","sourceRoot":"","sources":["../../src/search/hybrid.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;