ralph-hero-knowledge-index 0.1.0

package/dist/traverse.js

@@ -0,0 +1,91 @@
+export class Traverser {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    traverse(fromId, options = {}) {
+        const { type, depth = 3 } = options;
+        const typeFilter = type ? "AND r.type = @type" : "";
+        const sql = `
+      WITH RECURSIVE chain AS (
+        SELECT r.source_id, r.target_id, r.type, 1 AS depth
+        FROM relationships r
+        WHERE r.source_id = @fromId ${typeFilter}
+
+        UNION ALL
+
+        SELECT r.source_id, r.target_id, r.type, c.depth + 1
+        FROM relationships r
+        JOIN chain c ON r.source_id = c.target_id
+        WHERE c.depth < @depth ${typeFilter}
+      )
+      SELECT
+        chain.source_id AS sourceId,
+        chain.target_id AS targetId,
+        chain.type,
+        chain.depth,
+        d.title AS docTitle,
+        d.status AS docStatus,
+        d.date AS docDate
+      FROM chain
+      LEFT JOIN documents d ON d.id = chain.target_id
+      ORDER BY chain.depth, chain.target_id
+    `;
+        const params = { fromId, depth };
+        if (type)
+            params.type = type;
+        const rows = this.db.db.prepare(sql).all(params);
+        return rows.map((r) => ({
+            sourceId: r.sourceId,
+            targetId: r.targetId,
+            type: r.type,
+            depth: r.depth,
+            doc: r.docTitle != null
+                ? { title: r.docTitle, status: r.docStatus, date: r.docDate }
+                : null,
+        }));
+    }
+    traverseIncoming(toId, options = {}) {
+        const { type, depth = 3 } = options;
+        const typeFilter = type ? "AND r.type = @type" : "";
+        const sql = `
+      WITH RECURSIVE chain AS (
+        SELECT r.source_id, r.target_id, r.type, 1 AS depth
+        FROM relationships r
+        WHERE r.target_id = @toId ${typeFilter}
+
+        UNION ALL
+
+        SELECT r.source_id, r.target_id, r.type, c.depth + 1
+        FROM relationships r
+        JOIN chain c ON r.target_id = c.source_id
+        WHERE c.depth < @depth ${typeFilter}
+      )
+      SELECT
+        chain.source_id AS sourceId,
+        chain.target_id AS targetId,
+        chain.type,
+        chain.depth,
+        d.title AS docTitle,
+        d.status AS docStatus,
+        d.date AS docDate
+      FROM chain
+      LEFT JOIN documents d ON d.id = chain.source_id
+      ORDER BY chain.depth, chain.target_id
+    `;
+        const params = { toId, depth };
+        if (type)
+            params.type = type;
+        const rows = this.db.db.prepare(sql).all(params);
+        return rows.map((r) => ({
+            sourceId: r.sourceId,
+            targetId: r.targetId,
+            type: r.type,
+            depth: r.depth,
+            doc: r.docTitle != null
+                ? { title: r.docTitle, status: r.docStatus, date: r.docDate }
+                : null,
+        }));
+    }
+}
+//# sourceMappingURL=traverse.js.map

package/dist/traverse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traverse.js","sourceRoot":"","sources":["../src/traverse.ts"],"names":[],"mappings":"AAeA,MAAM,OAAO,SAAS;IACH,EAAE,CAAc;IAEjC,YAAY,EAAe;QACzB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;IAED,QAAQ,CAAC,MAAc,EAAE,UAA2B,EAAE;QACpD,MAAM,EAAE,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC;QACpC,MAAM,UAAU,GAAG,IAAI,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,CAAC;QAEpD,MAAM,GAAG,GAAG;;;;sCAIsB,UAAU;;;;;;;iCAOf,UAAU;;;;;;;;;;;;;KAatC,CAAC;QAEF,MAAM,MAAM,GAA4B,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QAC1D,IAAI,IAAI;YAAE,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC;QAE7B,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAQ7C,CAAC;QAEH,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,GAAG,EAAE,CAAC,CAAC,QAAQ,IAAI,IAAI;gBACrB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE;gBAC7D,CAAC,CAAC,IAAI;SACT,CAAC,CAAC,CAAC;IACN,CAAC;IAED,gBAAgB,CAAC,IAAY,EAAE,UAA2B,EAAE;QAC1D,MAAM,EAAE,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC;QACpC,MAAM,UAAU,GAAG,IAAI,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,CAAC;QAEpD,MAAM,GAAG,GAAG;;;;oCAIoB,UAAU;;;;;;;iCAOb,UAAU;;;;;;;;;;;;;KAatC,CAAC;QAEF,MAAM,MAAM,GAA4B,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QACxD,IAAI,IAAI;YAAE,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC;QAE7B,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAQ7C,CAAC;QAEH,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,GAAG,EAAE,CAAC,CAAC,QAAQ,IAAI,IAAI;gBACrB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE;gBAC7D,CAAC,CAAC,IAAI;SACT,CAAC,CAAC,CAAC;IACN,CAAC;CACF"}

package/dist/vector-search.d.ts

@@ -0,0 +1,15 @@
+import type { KnowledgeDB } from "./db.js";
+export interface VectorResult {
+    id: string;
+    distance: number;
+}
+export declare class VectorSearch {
+    private knowledgeDb;
+    private vecLoaded;
+    constructor(knowledgeDb: KnowledgeDB);
+    private ensureVecLoaded;
+    createIndex(): void;
+    dropIndex(): void;
+    upsertEmbedding(id: string, embedding: Float32Array): void;
+    search(queryEmbedding: Float32Array, limit?: number): VectorResult[];
+}

package/dist/vector-search.js

@@ -0,0 +1,52 @@
+import * as sqliteVec from "sqlite-vec";
+function float32ToBuffer(arr) {
+    return Buffer.from(arr.buffer, arr.byteOffset, arr.byteLength);
+}
+export class VectorSearch {
+    knowledgeDb;
+    vecLoaded = false;
+    constructor(knowledgeDb) {
+        this.knowledgeDb = knowledgeDb;
+    }
+    ensureVecLoaded() {
+        if (!this.vecLoaded) {
+            sqliteVec.load(this.knowledgeDb.db);
+            this.vecLoaded = true;
+        }
+    }
+    createIndex() {
+        this.ensureVecLoaded();
+        this.knowledgeDb.db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS documents_vec USING vec0(
+        id TEXT PRIMARY KEY,
+        embedding float[384] distance_metric=cosine
+      )
+    `);
+    }
+    dropIndex() {
+        this.knowledgeDb.db.exec("DROP TABLE IF EXISTS documents_vec");
+    }
+    upsertEmbedding(id, embedding) {
+        this.ensureVecLoaded();
+        const buf = float32ToBuffer(embedding);
+        this.knowledgeDb.db
+            .prepare("DELETE FROM documents_vec WHERE id = ?")
+            .run(id);
+        this.knowledgeDb.db
+            .prepare("INSERT INTO documents_vec (id, embedding) VALUES (?, ?)")
+            .run(id, buf);
+    }
+    search(queryEmbedding, limit = 10) {
+        this.ensureVecLoaded();
+        const buf = float32ToBuffer(queryEmbedding);
+        return this.knowledgeDb.db
+            .prepare(`
+      SELECT id, distance
+      FROM documents_vec
+      WHERE embedding MATCH ? AND k = ?
+      ORDER BY distance
+    `)
+            .all(buf, limit);
+    }
+}
+//# sourceMappingURL=vector-search.js.map

package/dist/vector-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-search.js","sourceRoot":"","sources":["../src/vector-search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,YAAY,CAAC;AAQxC,SAAS,eAAe,CAAC,GAAiB;IACxC,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;AACjE,CAAC;AAED,MAAM,OAAO,YAAY;IAGH;IAFZ,SAAS,GAAG,KAAK,CAAC;IAE1B,YAAoB,WAAwB;QAAxB,gBAAW,GAAX,WAAW,CAAa;IAAG,CAAC;IAExC,eAAe;QACrB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;YACpC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACxB,CAAC;IACH,CAAC;IAED,WAAW;QACT,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,IAAI,CAAC;;;;;KAKxB,CAAC,CAAC;IACL,CAAC;IAED,SAAS;QACP,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAC;IACjE,CAAC;IAED,eAAe,CAAC,EAAU,EAAE,SAAuB;QACjD,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;QACvC,IAAI,CAAC,WAAW,CAAC,EAAE;aAChB,OAAO,CAAC,wCAAwC,CAAC;aACjD,GAAG,CAAC,EAAE,CAAC,CAAC;QACX,IAAI,CAAC,WAAW,CAAC,EAAE;aAChB,OAAO,CAAC,yDAAyD,CAAC;aAClE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,CAAC,cAA4B,EAAE,QAAgB,EAAE;QACrD,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,eAAe,CAAC,cAAc,CAAC,CAAC;QAC5C,OAAO,IAAI,CAAC,WAAW,CAAC,EAAE;aACvB,OAAO,CACN;;;;;KAKH,CACE;aACA,GAAG,CAAC,GAAG,EAAE,KAAK,CAAmB,CAAC;IACvC,CAAC;CACF"}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "ralph-hero-knowledge-index",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "reindex": "node dist/reindex.js",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^3.0.0",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "better-sqlite3": "^12.6.0",
+    "sqlite-vec": "^0.1.7-alpha.10",
+    "yaml": "^2.7.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.0"
+  }
+}

package/src/__tests__/db.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { KnowledgeDB } from "../db.js";
+
+let db: KnowledgeDB;
+
+beforeEach(() => {
+  db = new KnowledgeDB(":memory:");
+});
+
+describe("KnowledgeDB", () => {
+  it("creates schema without error", () => {
+    expect(db).toBeTruthy();
+  });
+
+  it("inserts and retrieves a document", () => {
+    db.upsertDocument({ id: "doc-1", path: "thoughts/shared/research/doc-1.md", title: "Test Doc", date: "2026-03-08", type: "research", status: "draft", githubIssue: 100, content: "Some content about caching" });
+    const doc = db.getDocument("doc-1");
+    expect(doc).toBeTruthy();
+    expect(doc!.title).toBe("Test Doc");
+    expect(doc!.type).toBe("research");
+  });
+
+  it("inserts and retrieves tags", () => {
+    db.upsertDocument({ id: "doc-1", path: "p", title: "t", date: null, type: null, status: null, githubIssue: null, content: "" });
+    db.setTags("doc-1", ["caching", "performance"]);
+    expect(db.getTags("doc-1")).toEqual(["caching", "performance"]);
+  });
+
+  it("replaces tags on re-set", () => {
+    db.upsertDocument({ id: "doc-1", path: "p", title: "t", date: null, type: null, status: null, githubIssue: null, content: "" });
+    db.setTags("doc-1", ["old-tag"]);
+    db.setTags("doc-1", ["new-tag"]);
+    expect(db.getTags("doc-1")).toEqual(["new-tag"]);
+  });
+
+  it("inserts and retrieves relationships", () => {
+    db.upsertDocument({ id: "doc-a", path: "a", title: "A", date: null, type: null, status: null, githubIssue: null, content: "" });
+    db.upsertDocument({ id: "doc-b", path: "b", title: "B", date: null, type: null, status: null, githubIssue: null, content: "" });
+    db.addRelationship("doc-a", "doc-b", "builds_on");
+    const outgoing = db.getRelationshipsFrom("doc-a");
+    expect(outgoing).toHaveLength(1);
+    expect(outgoing[0]).toEqual({ sourceId: "doc-a", targetId: "doc-b", type: "builds_on" });
+    expect(db.getRelationshipsTo("doc-b")).toHaveLength(1);
+  });
+
+  it("clears all data for rebuild", () => {
+    db.upsertDocument({ id: "doc-1", path: "p", title: "t", date: null, type: null, status: null, githubIssue: null, content: "" });
+    db.clearAll();
+    expect(db.getDocument("doc-1")).toBeUndefined();
+  });
+});

package/src/__tests__/hybrid-search.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { KnowledgeDB } from "../db.js";
+import { FtsSearch } from "../search.js";
+import { VectorSearch } from "../vector-search.js";
+import { HybridSearch, type EmbedFn } from "../hybrid-search.js";
+
+let db: KnowledgeDB;
+let fts: FtsSearch;
+let vec: VectorSearch;
+let hybrid: HybridSearch;
+
+function mockEmbedding(seed: number): Float32Array {
+  const v = new Float32Array(384);
+  for (let i = 0; i < 384; i++) {
+    v[i] = Math.sin(seed * (i + 1) * 0.1);
+  }
+  let norm = 0;
+  for (let i = 0; i < v.length; i++) norm += v[i] * v[i];
+  norm = Math.sqrt(norm);
+  if (norm > 0) for (let i = 0; i < v.length; i++) v[i] /= norm;
+  return v;
+}
+
+/** Simple hash of a string to a numeric seed for deterministic mock embeddings. */
+function hashSeed(s: string): number {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) {
+    h = (h * 31 + s.charCodeAt(i)) | 0;
+  }
+  return Math.abs(h) % 1000;
+}
+
+const mockEmbedFn: EmbedFn = async (text: string) =>
+  mockEmbedding(hashSeed(text));
+
+beforeEach(() => {
+  db = new KnowledgeDB(":memory:");
+
+  db.upsertDocument({
+    id: "cache-doc",
+    path: "thoughts/shared/research/cache-strategies.md",
+    title: "Cache Invalidation Strategies",
+    date: "2026-03-01",
+    type: "research",
+    status: "draft",
+    githubIssue: null,
+    content:
+      "Analysis of cache invalidation patterns including TTL, event-driven, and write-through approaches.",
+  });
+  db.setTags("cache-doc", ["caching", "performance"]);
+
+  db.upsertDocument({
+    id: "auth-doc",
+    path: "thoughts/shared/plans/auth-redesign.md",
+    title: "Auth Redesign Plan",
+    date: "2026-03-02",
+    type: "plan",
+    status: "approved",
+    githubIssue: 42,
+    content:
+      "Redesign authentication to use OAuth2 with PKCE flow for improved security.",
+  });
+  db.setTags("auth-doc", ["auth", "security"]);
+
+  fts = new FtsSearch(db);
+  fts.rebuildIndex();
+
+  vec = new VectorSearch(db);
+  vec.createIndex();
+  vec.upsertEmbedding("cache-doc", mockEmbedding(1));
+  vec.upsertEmbedding("auth-doc", mockEmbedding(5));
+
+  hybrid = new HybridSearch(db, fts, vec, mockEmbedFn);
+});
+
+describe("HybridSearch", () => {
+  it("returns results combining FTS and vector scores", async () => {
+    const results = await hybrid.search("cache");
+
+    expect(results.length).toBeGreaterThanOrEqual(1);
+    // cache-doc should appear since it matches "cache" in FTS and also has a vector entry
+    const cacheResult = results.find((r) => r.id === "cache-doc");
+    expect(cacheResult).toBeDefined();
+    // RRF score should be positive
+    expect(cacheResult!.score).toBeGreaterThan(0);
+
+    // Results should be sorted descending by score
+    for (let i = 1; i < results.length; i++) {
+      expect(results[i - 1].score).toBeGreaterThanOrEqual(results[i].score);
+    }
+  });
+
+  it("passes through type filter", async () => {
+    const results = await hybrid.search("cache", { type: "plan" });
+
+    // cache-doc is type=research, so it should be excluded
+    const ids = results.map((r) => r.id);
+    expect(ids).not.toContain("cache-doc");
+  });
+
+  it("passes through tag filter", async () => {
+    const results = await hybrid.search("cache OR auth", {
+      tags: ["security"],
+    });
+
+    // Only auth-doc has the "security" tag
+    expect(results.length).toBeGreaterThanOrEqual(1);
+    const ids = results.map((r) => r.id);
+    expect(ids).toContain("auth-doc");
+    expect(ids).not.toContain("cache-doc");
+  });
+});

package/src/__tests__/index.test.ts

@@ -0,0 +1,8 @@
+import { describe, it, expect } from "vitest";
+
+describe("knowledge-index server", () => {
+  it("exports createServer function", async () => {
+    const mod = await import("../index.js");
+    expect(typeof mod.createServer).toBe("function");
+  });
+});

package/src/__tests__/parser.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect } from "vitest";
+import { parseDocument } from "../parser.js";
+
+const FULL_DOC = `---
+date: 2026-03-08
+github_issue: 560
+status: draft
+type: research
+tags: [caching, mcp-server, performance]
+---
+
+# GH-560: Response Cache TTL Strategy
+
+## Prior Work
+
+- builds_on:: [[2026-02-28-GH-0460-cache-invalidation-research]]
+- builds_on:: [[2026-03-01-GH-0480-session-cache-architecture]]
+- tensions:: [[2026-02-25-GH-0390-aggressive-caching-plan]]
+
+## Problem Statement
+
+The current cache has no TTL configuration.
+`;
+
+const SUPERSEDED_DOC = `---
+date: 2026-02-20
+github_issue: 200
+status: superseded
+type: plan
+tags: [caching]
+superseded_by: "[[2026-03-08-GH-0560-cache-ttl]]"
+---
+
+# GH-200: Old Caching Strategy
+
+Some old content.
+`;
+
+const MINIMAL_DOC = `---
+date: 2026-03-01
+type: idea
+---
+
+# A Simple Idea
+
+No prior work section.
+`;
+
+describe("parseDocument", () => {
+  it("parses frontmatter fields", () => {
+    const doc = parseDocument("2026-03-08-GH-0560-cache-ttl", "thoughts/shared/research/2026-03-08-GH-0560-cache-ttl.md", FULL_DOC);
+    expect(doc.id).toBe("2026-03-08-GH-0560-cache-ttl");
+    expect(doc.path).toBe("thoughts/shared/research/2026-03-08-GH-0560-cache-ttl.md");
+    expect(doc.date).toBe("2026-03-08");
+    expect(doc.type).toBe("research");
+    expect(doc.status).toBe("draft");
+    expect(doc.githubIssue).toBe(560);
+    expect(doc.tags).toEqual(["caching", "mcp-server", "performance"]);
+  });
+
+  it("extracts title from first heading", () => {
+    const doc = parseDocument("test", "test.md", FULL_DOC);
+    expect(doc.title).toBe("GH-560: Response Cache TTL Strategy");
+  });
+
+  it("extracts builds_on relationships from Prior Work", () => {
+    const doc = parseDocument("test", "test.md", FULL_DOC);
+    const buildsOn = doc.relationships.filter(r => r.type === "builds_on");
+    expect(buildsOn).toHaveLength(2);
+    expect(buildsOn[0].targetId).toBe("2026-02-28-GH-0460-cache-invalidation-research");
+    expect(buildsOn[1].targetId).toBe("2026-03-01-GH-0480-session-cache-architecture");
+  });
+
+  it("extracts tensions relationships from Prior Work", () => {
+    const doc = parseDocument("test", "test.md", FULL_DOC);
+    const tensions = doc.relationships.filter(r => r.type === "tensions");
+    expect(tensions).toHaveLength(1);
+    expect(tensions[0].targetId).toBe("2026-02-25-GH-0390-aggressive-caching-plan");
+  });
+
+  it("extracts superseded_by from frontmatter", () => {
+    const doc = parseDocument("test", "test.md", SUPERSEDED_DOC);
+    const superseded = doc.relationships.filter(r => r.type === "superseded_by");
+    expect(superseded).toHaveLength(1);
+    expect(superseded[0].targetId).toBe("2026-03-08-GH-0560-cache-ttl");
+  });
+
+  it("handles documents with no Prior Work section", () => {
+    const doc = parseDocument("test", "test.md", MINIMAL_DOC);
+    expect(doc.relationships).toEqual([]);
+    expect(doc.tags).toEqual([]);
+    expect(doc.title).toBe("A Simple Idea");
+  });
+
+  it("extracts content body for FTS indexing", () => {
+    const doc = parseDocument("test", "test.md", FULL_DOC);
+    expect(doc.content).toContain("current cache has no TTL");
+    expect(doc.content).not.toContain("---");
+  });
+});

package/src/__tests__/search.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { KnowledgeDB } from "../db.js";
+import { FtsSearch } from "../search.js";
+
+let db: KnowledgeDB;
+let fts: FtsSearch;
+
+beforeEach(() => {
+  db = new KnowledgeDB(":memory:");
+
+  db.upsertDocument({
+    id: "cache-doc",
+    path: "thoughts/shared/research/cache-strategies.md",
+    title: "Cache Invalidation Strategies",
+    date: "2026-03-01",
+    type: "research",
+    status: "draft",
+    githubIssue: null,
+    content: "Analysis of cache invalidation patterns including TTL, event-driven, and write-through approaches.",
+  });
+  db.setTags("cache-doc", ["caching", "performance"]);
+
+  db.upsertDocument({
+    id: "auth-doc",
+    path: "thoughts/shared/plans/auth-redesign.md",
+    title: "Auth Redesign Plan",
+    date: "2026-03-02",
+    type: "plan",
+    status: "approved",
+    githubIssue: 42,
+    content: "Redesign authentication to use OAuth2 with PKCE flow for improved security.",
+  });
+  db.setTags("auth-doc", ["auth", "security"]);
+
+  db.upsertDocument({
+    id: "cache-old",
+    path: "thoughts/shared/plans/old-cache-plan.md",
+    title: "Old Cache Plan",
+    date: "2026-01-15",
+    type: "plan",
+    status: "superseded",
+    githubIssue: null,
+    content: "Original cache implementation plan using Redis with simple TTL expiry.",
+  });
+  db.setTags("cache-old", ["caching"]);
+
+  fts = new FtsSearch(db);
+  fts.rebuildIndex();
+});
+
+describe("FtsSearch", () => {
+  it("finds documents by keyword", () => {
+    const results = fts.search("cache");
+    expect(results.length).toBeGreaterThanOrEqual(1);
+    expect(results[0].id).toBe("cache-doc");
+    expect(results[0].score).toBeLessThan(0);
+    expect(results[0].snippet).toBeTruthy();
+  });
+
+  it("returns empty for no matches", () => {
+    const results = fts.search("nonexistent");
+    expect(results).toHaveLength(0);
+  });
+
+  it("filters by type", () => {
+    const results = fts.search("cache", { type: "plan" });
+    expect(results).toHaveLength(0); // cache-old is superseded (excluded), cache-doc is research
+  });
+
+  it("filters by tags", () => {
+    const results = fts.search("cache OR auth", { tags: ["security"] });
+    expect(results).toHaveLength(1);
+    expect(results[0].id).toBe("auth-doc");
+  });
+
+  it("excludes superseded by default", () => {
+    const results = fts.search("cache");
+    const ids = results.map((r) => r.id);
+    expect(ids).not.toContain("cache-old");
+  });
+
+  it("includes superseded when requested", () => {
+    const results = fts.search("cache", { includeSuperseded: true });
+    const ids = results.map((r) => r.id);
+    expect(ids).toContain("cache-old");
+  });
+
+  it("respects limit", () => {
+    const results = fts.search("cache", { includeSuperseded: true, limit: 1 });
+    expect(results).toHaveLength(1);
+  });
+});

package/src/__tests__/traverse.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { KnowledgeDB } from "../db.js";
+import { Traverser } from "../traverse.js";
+
+let db: KnowledgeDB;
+let traverser: Traverser;
+
+beforeEach(() => {
+  db = new KnowledgeDB(":memory:");
+
+  // Chain: doc-c builds_on doc-b builds_on doc-a
+  // Plus: doc-c tensions doc-a
+  db.upsertDocument({
+    id: "doc-a",
+    path: "thoughts/shared/research/doc-a.md",
+    title: "Foundation Research",
+    date: "2026-02-01",
+    type: "research",
+    status: "approved",
+    githubIssue: null,
+    content: "Foundational research document.",
+  });
+
+  db.upsertDocument({
+    id: "doc-b",
+    path: "thoughts/shared/plans/doc-b.md",
+    title: "Implementation Plan",
+    date: "2026-02-15",
+    type: "plan",
+    status: "draft",
+    githubIssue: 10,
+    content: "Plan that builds on foundation.",
+  });
+
+  db.upsertDocument({
+    id: "doc-c",
+    path: "thoughts/shared/plans/doc-c.md",
+    title: "Revised Plan",
+    date: "2026-03-01",
+    type: "plan",
+    status: "draft",
+    githubIssue: 20,
+    content: "Revised plan that builds on implementation and tensions with foundation.",
+  });
+
+  db.addRelationship("doc-b", "doc-a", "builds_on");
+  db.addRelationship("doc-c", "doc-b", "builds_on");
+  db.addRelationship("doc-c", "doc-a", "tensions");
+
+  traverser = new Traverser(db);
+});
+
+describe("Traverser", () => {
+  it("finds direct outgoing relationships", () => {
+    const results = traverser.traverse("doc-c", { depth: 1 });
+    expect(results).toHaveLength(2);
+    const targetIds = results.map((r) => r.targetId).sort();
+    expect(targetIds).toEqual(["doc-a", "doc-b"]);
+  });
+
+  it("walks multi-hop builds_on chain", () => {
+    const results = traverser.traverse("doc-c", { type: "builds_on" });
+    expect(results).toHaveLength(2);
+    expect(results[0]).toMatchObject({ sourceId: "doc-c", targetId: "doc-b", depth: 1 });
+    expect(results[1]).toMatchObject({ sourceId: "doc-b", targetId: "doc-a", depth: 2 });
+  });
+
+  it("respects depth limit", () => {
+    const results = traverser.traverse("doc-c", { type: "builds_on", depth: 1 });
+    expect(results).toHaveLength(1);
+    expect(results[0].targetId).toBe("doc-b");
+  });
+
+  it("filters by relationship type", () => {
+    const results = traverser.traverse("doc-c", { type: "tensions" });
+    expect(results).toHaveLength(1);
+    expect(results[0]).toMatchObject({ sourceId: "doc-c", targetId: "doc-a", type: "tensions" });
+  });
+
+  it("finds incoming relationships", () => {
+    const results = traverser.traverseIncoming("doc-a");
+    // doc-b builds_on doc-a (depth 1), doc-c tensions doc-a (depth 1), doc-c builds_on doc-b (depth 2)
+    expect(results.length).toBeGreaterThanOrEqual(2);
+    const depth1 = results.filter((r) => r.depth === 1);
+    const sourceIds = depth1.map((r) => r.sourceId).sort();
+    expect(sourceIds).toEqual(["doc-b", "doc-c"]);
+  });
+
+  it("includes document metadata in results", () => {
+    const results = traverser.traverse("doc-c", { type: "builds_on", depth: 1 });
+    expect(results).toHaveLength(1);
+    expect(results[0].doc).toEqual({
+      title: "Implementation Plan",
+      status: "draft",
+      date: "2026-02-15",
+    });
+  });
+
+  it("returns empty for document with no relationships", () => {
+    db.upsertDocument({
+      id: "doc-orphan",
+      path: "thoughts/shared/ideas/orphan.md",
+      title: "Orphan Idea",
+      date: "2026-03-05",
+      type: "idea",
+      status: "draft",
+      githubIssue: null,
+      content: "An isolated idea with no connections.",
+    });
+    const outgoing = traverser.traverse("doc-orphan");
+    const incoming = traverser.traverseIncoming("doc-orphan");
+    expect(outgoing).toHaveLength(0);
+    expect(incoming).toHaveLength(0);
+  });
+});