Persistent project knowledge graph for coding agents. MCP server with semantic search, in-process embeddings, and web explorer.
TypeScript agentic-codingaiai-agentsclaude-codecode-contextcoding-agentembeddingsknowledge-graphllmmcpmcp-serveropencodepersistent-memorysqlitetypescript
fix: add SQLite concurrency safety for multi-process MCP access
0xk3vin9c361e2e6b15
diff --git a/src/__tests__/db.test.ts b/src/__tests__/db.test.tsindex 805a9ba..b87f56f 100644--- a/src/__tests__/db.test.ts+++ b/src/__tests__/db.test.ts@@ -345,6 +345,123 @@ describe("KnowledgeDB", () => {expect(edges[0].from_id).toBe("node-a");expect(edges[0].to_id).toBe("node-b");});++ it("silently ignores duplicate edges", () => {+ const first = db.insertEdge({+ from_id: "node-a",+ to_id: "node-b",+ relation: "depends_on",+ description: "first",+ });+ const second = db.insertEdge({+ from_id: "node-a",+ to_id: "node-b",+ relation: "depends_on",+ description: "duplicate",+ });++ expect(first.inserted).toBe(true);+ expect(second.inserted).toBe(false);+ expect(db.getAllEdges()).toHaveLength(1);+ });++ it("allows multiple relations between the same nodes", () => {+ const depends = db.insertEdge({+ from_id: "node-a",+ to_id: "node-b",+ relation: "depends_on",+ description: null,+ });+ const calls = db.insertEdge({+ from_id: "node-a",+ to_id: "node-b",+ relation: "calls",+ description: null,+ });++ expect(depends.inserted).toBe(true);+ expect(calls.inserted).toBe(true);+ expect(db.getAllEdges()).toHaveLength(2);+ });+ });++ describe("transactions", () => {+ it("insertNodeAndEdges inserts node and valid edges atomically", () => {+ db.insertNode({+ id: "target",+ name: "Target",+ kind: "feature",+ summary: "target",+ why: null,+ file_refs: null,+ parent_id: null,+ created_by_task: null,+ embedding: null,+ });++ db.insertNodeAndEdges(+ {+ id: "source",+ name: "Source",+ kind: "feature",+ summary: "source",+ why: null,+ file_refs: JSON.stringify(["src/source.ts"]),+ parent_id: null,+ created_by_task: null,+ embedding: null,+ },+ [{ to_id: "target", relation: "calls", description: "source calls target" }]+ );++ expect(db.getNode("source")).toBeDefined();+ const outgoing = db.getOutgoingEdges("source");+ expect(outgoing).toHaveLength(1);+ expect(outgoing[0].to_id).toBe("target");+ expect(outgoing[0].relation).toBe("calls");+ });++ it("insertNodeAndEdges skips edges to nonexistent targets", () => {+ db.insertNodeAndEdges(+ {+ id: "source-only",+ name: "Source Only",+ kind: "feature",+ summary: "source",+ why: null,+ file_refs: null,+ parent_id: null,+ created_by_task: null,+ embedding: null,+ },+ [{ to_id: "missing", relation: "calls", description: null }]+ );++ expect(db.getNode("source-only")).toBeDefined();+ expect(db.getOutgoingEdges("source-only")).toHaveLength(0);+ expect(db.getAllEdges()).toHaveLength(0);+ });++ it("runInTransaction rolls back when callback throws", () => {+ expect(() => {+ db.runInTransaction(() => {+ db.insertNode({+ id: "rolled-back",+ name: "Rolled Back",+ kind: "feature",+ summary: "should not persist",+ why: null,+ file_refs: null,+ parent_id: null,+ created_by_task: null,+ embedding: null,+ });+ throw new Error("force rollback");+ });+ }).toThrow("force rollback");++ expect(db.getNode("rolled-back")).toBeUndefined();+ });});describe("schema v2 - merge columns", () => {diff --git a/src/__tests__/timeline.test.ts b/src/__tests__/timeline.test.tsindex 2670d42..d49af69 100644--- a/src/__tests__/timeline.test.ts+++ b/src/__tests__/timeline.test.ts@@ -457,7 +457,7 @@ describe("KnowledgeDB timeline", () => {});describe("schema migration", () => {- it("verifies schema version is 3", () => {+ it("verifies schema version is 4", () => {const rawDb = new Database(dbPath);const pragmaResult = rawDb.pragma("user_version", { simple: true }) as| number@@ -468,7 +468,7 @@ describe("KnowledgeDB timeline", () => {typeof pragmaResult === "object"? pragmaResult.user_version: pragmaResult;- expect(version).toBe(3);+ expect(version).toBe(4);});it("verifies timeline table exists with correct columns", () => {diff --git a/src/db.ts b/src/db.tsindex a6a7820..26e47a8 100644--- a/src/db.ts+++ b/src/db.ts@@ -3,7 +3,7 @@ import path from "path";import fs from "fs";import type { NodeRow, EdgeRow } from "./types.js";-const SCHEMA_VERSION = 3;+const SCHEMA_VERSION = 4;export class KnowledgeDB {private db: Database.Database;@@ -18,127 +18,173 @@ export class KnowledgeDB {this.db = new Database(dbPath);this.db.pragma("journal_mode = WAL");this.db.pragma("foreign_keys = ON");+ this.db.pragma("busy_timeout = 1000");+ this.db.pragma("synchronous = NORMAL");this.migrate();}- private migrate(): void {+ private getUserVersion(): number {const pragmaResult = this.db.pragma("user_version", { simple: true });// libsql returns { user_version: N } instead of raw N like better-sqlite3- const version = (+ return (typeof pragmaResult === "object" && pragmaResult !== null? (pragmaResult as Record<string, unknown>).user_version: pragmaResult) as number;+ }- if (version < 1) {- this.db.exec(`- CREATE TABLE IF NOT EXISTS nodes (- id TEXT PRIMARY KEY,- name TEXT NOT NULL,- kind TEXT NOT NULL,- summary TEXT NOT NULL,- why TEXT,- file_refs TEXT,- parent_id TEXT,- created_by_task TEXT,- created_at TEXT DEFAULT (datetime('now')),- updated_at TEXT DEFAULT (datetime('now')),- removed_at TEXT,- removed_reason TEXT,- embedding BLOB,- merge_group TEXT,- needs_merge INTEGER DEFAULT 0,- source_branch TEXT,- merge_timestamp TEXT,- FOREIGN KEY (parent_id) REFERENCES nodes(id) ON DELETE SET NULL- );-- CREATE TABLE IF NOT EXISTS edges (- id INTEGER PRIMARY KEY AUTOINCREMENT,- from_id TEXT NOT NULL,- to_id TEXT NOT NULL,- relation TEXT NOT NULL,- description TEXT,- created_at TEXT DEFAULT (datetime('now')),- merge_group TEXT,- needs_merge INTEGER DEFAULT 0,- source_branch TEXT,- merge_timestamp TEXT,- FOREIGN KEY (from_id) REFERENCES nodes(id) ON DELETE CASCADE,- FOREIGN KEY (to_id) REFERENCES nodes(id) ON DELETE CASCADE- );-- CREATE INDEX IF NOT EXISTS idx_nodes_parent ON nodes(parent_id);- CREATE INDEX IF NOT EXISTS idx_nodes_kind ON nodes(kind);- CREATE INDEX IF NOT EXISTS idx_nodes_removed ON nodes(removed_at);- CREATE INDEX IF NOT EXISTS idx_nodes_merge_group ON nodes(merge_group);- CREATE INDEX IF NOT EXISTS idx_nodes_needs_merge ON nodes(needs_merge);- CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(from_id);- CREATE INDEX IF NOT EXISTS idx_edges_to ON edges(to_id);- CREATE INDEX IF NOT EXISTS idx_edges_relation ON edges(relation);- CREATE INDEX IF NOT EXISTS idx_edges_merge_group ON edges(merge_group);- CREATE INDEX IF NOT EXISTS idx_edges_needs_merge ON edges(needs_merge);- `);- }+ private migrate(): void {+ const version = this.getUserVersion();+ if (version >= SCHEMA_VERSION) return;- if (version < 2) {- // Add merge-related columns for existing v1 databases- const nodeColumns = this.db- .prepare("PRAGMA table_info(nodes)")- .all() as Array<{ name: string }>;- const nodeColNames = new Set(nodeColumns.map((c) => c.name));+ this.db.exec("BEGIN IMMEDIATE");+ try {+ // Re-check after acquiring the write lock in case another process migrated first.+ const currentVersion = this.getUserVersion();+ if (currentVersion >= SCHEMA_VERSION) {+ this.db.exec("COMMIT");+ return;+ }- if (!nodeColNames.has("merge_group")) {+ if (currentVersion < 1) {this.db.exec(`- ALTER TABLE nodes ADD COLUMN merge_group TEXT;- ALTER TABLE nodes ADD COLUMN needs_merge INTEGER DEFAULT 0;- ALTER TABLE nodes ADD COLUMN source_branch TEXT;- ALTER TABLE nodes ADD COLUMN merge_timestamp TEXT;+ CREATE TABLE IF NOT EXISTS nodes (+ id TEXT PRIMARY KEY,+ name TEXT NOT NULL,+ kind TEXT NOT NULL,+ summary TEXT NOT NULL,+ why TEXT,+ file_refs TEXT,+ parent_id TEXT,+ created_by_task TEXT,+ created_at TEXT DEFAULT (datetime('now')),+ updated_at TEXT DEFAULT (datetime('now')),+ removed_at TEXT,+ removed_reason TEXT,+ embedding BLOB,+ merge_group TEXT,+ needs_merge INTEGER DEFAULT 0,+ source_branch TEXT,+ merge_timestamp TEXT,+ FOREIGN KEY (parent_id) REFERENCES nodes(id) ON DELETE SET NULL+ );++ CREATE TABLE IF NOT EXISTS edges (+ id INTEGER PRIMARY KEY AUTOINCREMENT,+ from_id TEXT NOT NULL,+ to_id TEXT NOT NULL,+ relation TEXT NOT NULL,+ description TEXT,+ created_at TEXT DEFAULT (datetime('now')),+ merge_group TEXT,+ needs_merge INTEGER DEFAULT 0,+ source_branch TEXT,+ merge_timestamp TEXT,+ FOREIGN KEY (from_id) REFERENCES nodes(id) ON DELETE CASCADE,+ FOREIGN KEY (to_id) REFERENCES nodes(id) ON DELETE CASCADE+ );++ CREATE INDEX IF NOT EXISTS idx_nodes_parent ON nodes(parent_id);+ CREATE INDEX IF NOT EXISTS idx_nodes_kind ON nodes(kind);+ CREATE INDEX IF NOT EXISTS idx_nodes_removed ON nodes(removed_at);CREATE INDEX IF NOT EXISTS idx_nodes_merge_group ON nodes(merge_group);CREATE INDEX IF NOT EXISTS idx_nodes_needs_merge ON nodes(needs_merge);+ CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(from_id);+ CREATE INDEX IF NOT EXISTS idx_edges_to ON edges(to_id);+ CREATE INDEX IF NOT EXISTS idx_edges_relation ON edges(relation);+ CREATE INDEX IF NOT EXISTS idx_edges_merge_group ON edges(merge_group);+ CREATE INDEX IF NOT EXISTS idx_edges_needs_merge ON edges(needs_merge);`);}- const edgeColumns = this.db- .prepare("PRAGMA table_info(edges)")- .all() as Array<{ name: string }>;- const edgeColNames = new Set(edgeColumns.map((c) => c.name));+ if (currentVersion < 2) {+ // Add merge-related columns for existing v1 databases+ const nodeColumns = this.db+ .prepare("PRAGMA table_info(nodes)")+ .all() as Array<{ name: string }>;+ const nodeColNames = new Set(nodeColumns.map((c) => c.name));++ if (!nodeColNames.has("merge_group")) {+ this.db.exec(`+ ALTER TABLE nodes ADD COLUMN merge_group TEXT;+ ALTER TABLE nodes ADD COLUMN needs_merge INTEGER DEFAULT 0;+ ALTER TABLE nodes ADD COLUMN source_branch TEXT;+ ALTER TABLE nodes ADD COLUMN merge_timestamp TEXT;+ CREATE INDEX IF NOT EXISTS idx_nodes_merge_group ON nodes(merge_group);+ CREATE INDEX IF NOT EXISTS idx_nodes_needs_merge ON nodes(needs_merge);+ `);+ }- if (!edgeColNames.has("merge_group")) {+ const edgeColumns = this.db+ .prepare("PRAGMA table_info(edges)")+ .all() as Array<{ name: string }>;+ const edgeColNames = new Set(edgeColumns.map((c) => c.name));++ if (!edgeColNames.has("merge_group")) {+ this.db.exec(`+ ALTER TABLE edges ADD COLUMN merge_group TEXT;+ ALTER TABLE edges ADD COLUMN needs_merge INTEGER DEFAULT 0;+ ALTER TABLE edges ADD COLUMN source_branch TEXT;+ ALTER TABLE edges ADD COLUMN merge_timestamp TEXT;+ CREATE INDEX IF NOT EXISTS idx_edges_merge_group ON edges(merge_group);+ CREATE INDEX IF NOT EXISTS idx_edges_needs_merge ON edges(needs_merge);+ `);+ }+ }++ if (currentVersion < 3) {+ // Add timeline table for version 3this.db.exec(`- ALTER TABLE edges ADD COLUMN merge_group TEXT;- ALTER TABLE edges ADD COLUMN needs_merge INTEGER DEFAULT 0;- ALTER TABLE edges ADD COLUMN source_branch TEXT;- ALTER TABLE edges ADD COLUMN merge_timestamp TEXT;- CREATE INDEX IF NOT EXISTS idx_edges_merge_group ON edges(merge_group);- CREATE INDEX IF NOT EXISTS idx_edges_needs_merge ON edges(needs_merge);+ CREATE TABLE IF NOT EXISTS timeline (+ seq INTEGER PRIMARY KEY AUTOINCREMENT,+ timestamp TEXT DEFAULT (datetime('now')),+ tool TEXT NOT NULL,+ params TEXT NOT NULL,+ result_summary TEXT NOT NULL,+ is_write INTEGER NOT NULL,+ is_error INTEGER NOT NULL,+ affected_ids TEXT NOT NULL+ );++ CREATE INDEX IF NOT EXISTS idx_timeline_timestamp ON timeline(timestamp);+ CREATE INDEX IF NOT EXISTS idx_timeline_tool ON timeline(tool);+ CREATE INDEX IF NOT EXISTS idx_timeline_is_write ON timeline(is_write);+ CREATE INDEX IF NOT EXISTS idx_timeline_is_error ON timeline(is_error);`);}- }- if (version < 3) {- // Add timeline table for version 3- this.db.exec(`- CREATE TABLE IF NOT EXISTS timeline (- seq INTEGER PRIMARY KEY AUTOINCREMENT,- timestamp TEXT DEFAULT (datetime('now')),- tool TEXT NOT NULL,- params TEXT NOT NULL,- result_summary TEXT NOT NULL,- is_write INTEGER NOT NULL,- is_error INTEGER NOT NULL,- affected_ids TEXT NOT NULL- );-- CREATE INDEX IF NOT EXISTS idx_timeline_timestamp ON timeline(timestamp);- CREATE INDEX IF NOT EXISTS idx_timeline_tool ON timeline(tool);- CREATE INDEX IF NOT EXISTS idx_timeline_is_write ON timeline(is_write);- CREATE INDEX IF NOT EXISTS idx_timeline_is_error ON timeline(is_error);- `);- }+ if (currentVersion < 4) {+ this.db.exec(`+ DELETE FROM edges+ WHERE id NOT IN (+ SELECT MIN(id)+ FROM edges+ GROUP BY from_id, to_id, relation+ )+ `);+ this.db.exec(`+ CREATE UNIQUE INDEX IF NOT EXISTS idx_edges_unique+ ON edges(from_id, to_id, relation)+ `);+ }- if (version < SCHEMA_VERSION) {this.db.pragma(`user_version = ${SCHEMA_VERSION}`);+ this.db.exec("COMMIT");+ } catch (err) {+ this.db.exec("ROLLBACK");+ throw err;+ }+ }++ runInTransaction<T>(fn: () => T): T {+ this.db.exec("BEGIN IMMEDIATE");+ try {+ const result = fn();+ this.db.exec("COMMIT");+ return result;+ } catch (err) {+ this.db.exec("ROLLBACK");+ throw err;}}@@ -172,6 +218,48 @@ export class KnowledgeDB {});}+ insertNodeAndEdges(+ node: {+ id: string;+ name: string;+ kind: string;+ summary: string;+ why: string | null;+ file_refs: string | null;+ parent_id: string | null;+ created_by_task: string | null;+ embedding: Buffer | null;+ },+ edges: Array<{ to_id: string; relation: string; description: string | null }>+ ): void {+ this.runInTransaction(() => {+ this.insertNode({+ id: node.id,+ name: node.name,+ kind: node.kind,+ summary: node.summary,+ why: node.why,+ file_refs: node.file_refs+ ? (JSON.parse(node.file_refs) as string[])+ : null,+ parent_id: node.parent_id,+ created_by_task: node.created_by_task,+ embedding: node.embedding,+ });++ for (const edge of edges) {+ if (this.nodeExists(edge.to_id)) {+ this.insertEdge({+ from_id: node.id,+ to_id: edge.to_id,+ relation: edge.relation,+ description: edge.description,+ });+ }+ }+ });+ }+getNode(id: string): NodeRow | undefined {return this.db.prepare("SELECT * FROM nodes WHERE id = ? AND removed_at IS NULL")@@ -258,9 +346,9 @@ export class KnowledgeDB {to_id: string;relation: string;description?: string | null;- }): number {+ }): { id: number; inserted: boolean } {const stmt = this.db.prepare(`- INSERT INTO edges (from_id, to_id, relation, description)+ INSERT OR IGNORE INTO edges (from_id, to_id, relation, description)VALUES (@from_id, @to_id, @relation, @description)`);const result = stmt.run({@@ -269,7 +357,10 @@ export class KnowledgeDB {relation: edge.relation,description: edge.description ?? null,});- return Number(result.lastInsertRowid);+ return {+ id: Number(result.lastInsertRowid),+ inserted: result.changes > 0,+ };}deleteEdge(fromId: string, toId: string, relation: string): boolean {@@ -477,8 +568,7 @@ export class KnowledgeDB {this.db.pragma("foreign_keys = OFF");try {let changed = false;- this.db.exec("BEGIN");- try {+ this.runInTransaction(() => {const result = this.db.prepare("UPDATE nodes SET id = @newId, updated_at = datetime('now') WHERE id = @oldId").run({ oldId, newId });@@ -497,11 +587,7 @@ export class KnowledgeDB {.prepare("UPDATE edges SET to_id = @newId WHERE to_id = @oldId").run({ oldId, newId });}- this.db.exec("COMMIT");- } catch (err) {- this.db.exec("ROLLBACK");- throw err;- }+ });return changed;} finally {this.db.pragma("foreign_keys = ON");@@ -590,7 +676,7 @@ export class KnowledgeDB {merge_timestamp?: string | null;}): number {const stmt = this.db.prepare(`- INSERT INTO edges (from_id, to_id, relation, description, created_at,+ INSERT OR IGNORE INTO edges (from_id, to_id, relation, description, created_at,merge_group, needs_merge, source_branch, merge_timestamp)VALUES (@from_id, @to_id, @relation, @description, @created_at,@merge_group, @needs_merge, @source_branch, @merge_timestamp)diff --git a/src/tools.ts b/src/tools.tsindex 222970c..1981cf0 100644--- a/src/tools.ts+++ b/src/tools.ts@@ -155,33 +155,24 @@ export async function createConcept(const text = embeddingText(input.name, input.kind, input.summary);const embedding = await embed(text);- // Insert node- db.insertNode({- id,- name: input.name,- kind: input.kind,- summary: input.summary,- why: input.why,- file_refs: input.file_refs,- parent_id: input.parent_id,- created_by_task: input.created_by_task,- embedding,- });-- // Create edges if specified- if (input.edges) {- for (const edge of input.edges) {- // Only create edge if target exists- if (db.nodeExists(edge.to)) {- db.insertEdge({- from_id: id,- to_id: edge.to,- relation: edge.relation,- description: edge.description,- });- }- }- }+ db.insertNodeAndEdges(+ {+ id,+ name: input.name,+ kind: input.kind,+ summary: input.summary,+ why: input.why ?? null,+ file_refs: input.file_refs ? JSON.stringify(input.file_refs) : null,+ parent_id: input.parent_id ?? null,+ created_by_task: input.created_by_task ?? null,+ embedding,+ },+ (input.edges ?? []).map((edge) => ({+ to_id: edge.to,+ relation: edge.relation,+ description: edge.description ?? null,+ }))+ );return { id, message: `Created concept "${id}"` };}@@ -230,13 +221,19 @@ export function link(throw new Error(`Target concept "${input.to}" not found.`);}- const edgeId = db.insertEdge({+ const { id: edgeId, inserted } = db.insertEdge({from_id: input.from,to_id: input.to,relation: input.relation,description: input.description,});+ if (!inserted) {+ return {+ message: `Relationship "${input.relation}" from "${input.from}" to "${input.to}" already exists.`,+ };+ }+return {message: `Created ${input.relation} link from "${input.from}" to "${input.to}" (edge #${edgeId})`,};