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
add timeline tests, root size check script, and debug assets
0xk3vin250b34ba091c
diff --git a/debug/image.png b/debug/image.pngnew file mode 100644index 0000000..07f4075Binary files /dev/null and b/debug/image.png differdiff --git a/scripts/check-roots-size.sh b/scripts/check-roots-size.shnew file mode 100755index 0000000..d3e28d7--- /dev/null+++ b/scripts/check-roots-size.sh@@ -0,0 +1,20 @@+#!/usr/bin/env bash+# Usage: scripts/check-roots-size.sh [db_path]+set -euo pipefail++DB="${1:-${MEGAMEMORY_DB_PATH:-.megamemory/knowledge.db}}"+command -v sqlite3 >/dev/null || { echo "sqlite3 not found in PATH"; exit 1; }+[[ -f "$DB" ]] || { echo "Database not found: $DB"; exit 1; }++ROOT_JSON="json_object('name',r.name,'summary',r.summary,'children',coalesce((select json_group_array(json_object('id',c.id,'name',c.name,'kind',c.kind,'summary',c.summary)) from nodes c where c.parent_id=r.id and c.removed_at is null),'[]'))"++echo "DB: $DB"+COUNT="$(sqlite3 "$DB" "select count(*) from nodes where parent_id is null and removed_at is null;")"+echo "Root concepts: $COUNT"+echo "Per-root JSON bytes:"+sqlite3 -separator $'\t' "$DB" "select r.name, length($ROOT_JSON) from nodes r where r.parent_id is null and r.removed_at is null order by r.name;" |+while IFS=$'\t' read -r name bytes; do printf " - %s: %s\n" "$name" "$bytes"; done++TOTAL="$(sqlite3 "$DB" "select length(json_object('roots',coalesce((select json_group_array(json(root_json)) from (select $ROOT_JSON as root_json from nodes r where r.parent_id is null and r.removed_at is null order by r.name)),json('[]'))));")"+echo "Total response bytes: $TOTAL"+echo "Estimated tokens (~chars/4): $(((TOTAL + 3) / 4))"diff --git a/src/__tests__/timeline.test.ts b/src/__tests__/timeline.test.tsnew file mode 100644index 0000000..2670d42--- /dev/null+++ b/src/__tests__/timeline.test.ts@@ -0,0 +1,494 @@+import { describe, it, expect, beforeEach, afterEach } from "vitest";+import Database from "libsql";+import { KnowledgeDB } from "../db.js";+import fs from "fs";+import path from "path";+import os from "os";++let db: KnowledgeDB;+let dbPath: string;+let tmpDir: string;++beforeEach(() => {+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "megamemory-timeline-test-"));+ dbPath = path.join(tmpDir, "knowledge.db");+ db = new KnowledgeDB(dbPath);+});++afterEach(() => {+ db.close();+ fs.rmSync(tmpDir, { recursive: true, force: true });+});++function setTimelineTimestamp(seq: number, timestamp: string): void {+ const rawDb = new Database(dbPath);+ rawDb.prepare("UPDATE timeline SET timestamp = ? WHERE seq = ?").run(timestamp, seq);+ rawDb.close();+}++function setNodeRemovedAt(nodeId: string, removedAt: string): void {+ const rawDb = new Database(dbPath);+ rawDb.prepare("UPDATE nodes SET removed_at = ? WHERE id = ?").run(removedAt, nodeId);+ rawDb.close();+}++describe("KnowledgeDB timeline", () => {+ describe("timeline entry CRUD", () => {+ it("insertTimelineEntry creates an entry and returns a seq number", () => {+ const seq = db.insertTimelineEntry({+ tool: "create_concept",+ params: JSON.stringify({ name: "Timeline Test" }),+ result_summary: "Created concept",+ is_write: true,+ is_error: false,+ affected_ids: ["timeline-test"],+ });++ expect(seq).toBe(1);+ });++ it("insertTimelineEntry stores correct fields", () => {+ const seq = db.insertTimelineEntry({+ tool: "update_concept",+ params: JSON.stringify({ id: "a", changes: { summary: "s" } }),+ result_summary: "Updated concept a",+ is_write: true,+ is_error: true,+ affected_ids: ["a", "a/child"],+ });++ const entries = db.getTimelineEntries();+ expect(entries).toHaveLength(1);+ expect(entries[0].seq).toBe(seq);+ expect(entries[0].tool).toBe("update_concept");+ expect(entries[0].params).toBe(+ JSON.stringify({ id: "a", changes: { summary: "s" } })+ );+ expect(entries[0].result_summary).toBe("Updated concept a");+ expect(entries[0].is_write).toBe(1);+ expect(entries[0].is_error).toBe(1);+ expect(entries[0].affected_ids).toBe(JSON.stringify(["a", "a/child"]));+ });++ it("multiple entries get incrementing seq numbers", () => {+ const seq1 = db.insertTimelineEntry({+ tool: "list_roots",+ params: "{}",+ result_summary: "Listed roots",+ is_write: false,+ is_error: false,+ affected_ids: [],+ });+ const seq2 = db.insertTimelineEntry({+ tool: "understand",+ params: JSON.stringify({ query: "x" }),+ result_summary: "Returned matches",+ is_write: false,+ is_error: false,+ affected_ids: [],+ });+ const seq3 = db.insertTimelineEntry({+ tool: "create_concept",+ params: JSON.stringify({ name: "New" }),+ result_summary: "Created",+ is_write: true,+ is_error: false,+ affected_ids: ["new"],+ });++ expect(seq1).toBe(1);+ expect(seq2).toBe(2);+ expect(seq3).toBe(3);+ });+ });++ describe("timeline queries", () => {+ it("getTimelineBounds returns null first/last and count 0 for empty timeline", () => {+ const bounds = db.getTimelineBounds();++ expect(bounds.first).toBeNull();+ expect(bounds.last).toBeNull();+ expect(bounds.count).toBe(0);+ });++ it("getTimelineBounds returns correct first, last, and count after inserting entries", () => {+ const seq1 = db.insertTimelineEntry({+ tool: "t1",+ params: "{}",+ result_summary: "r1",+ is_write: false,+ is_error: false,+ affected_ids: [],+ });+ const seq2 = db.insertTimelineEntry({+ tool: "t2",+ params: "{}",+ result_summary: "r2",+ is_write: true,+ is_error: false,+ affected_ids: ["x"],+ });++ setTimelineTimestamp(seq1, "2026-02-10T10:00:00.000Z");+ setTimelineTimestamp(seq2, "2026-02-10T11:00:00.000Z");++ const bounds = db.getTimelineBounds();+ expect(bounds.first).toBe("2026-02-10T10:00:00.000Z");+ expect(bounds.last).toBe("2026-02-10T11:00:00.000Z");+ expect(bounds.count).toBe(2);+ });++ it("getTimelineEntries returns all entries in seq order", () => {+ db.insertTimelineEntry({+ tool: "a",+ params: "{}",+ result_summary: "ra",+ is_write: false,+ is_error: false,+ affected_ids: [],+ });+ db.insertTimelineEntry({+ tool: "b",+ params: "{}",+ result_summary: "rb",+ is_write: false,+ is_error: false,+ affected_ids: [],+ });+ db.insertTimelineEntry({+ tool: "c",+ params: "{}",+ result_summary: "rc",+ is_write: false,+ is_error: false,+ affected_ids: [],+ });++ const entries = db.getTimelineEntries();+ expect(entries.map((e) => e.seq)).toEqual([1, 2, 3]);+ });++ it("getTimelineEntries with limit works", () => {+ db.insertTimelineEntry({+ tool: "a",+ params: "{}",+ result_summary: "ra",+ is_write: false,+ is_error: false,+ affected_ids: [],+ });+ db.insertTimelineEntry({+ tool: "b",+ params: "{}",+ result_summary: "rb",+ is_write: false,+ is_error: false,+ affected_ids: [],+ });+ db.insertTimelineEntry({+ tool: "c",+ params: "{}",+ result_summary: "rc",+ is_write: false,+ is_error: false,+ affected_ids: [],+ });++ const entries = db.getTimelineEntries({ limit: 2 });+ expect(entries).toHaveLength(2);+ expect(entries.map((e) => e.seq)).toEqual([1, 2]);+ });++ it("getTimelineEntries with tool filter works", () => {+ db.insertTimelineEntry({+ tool: "understand",+ params: "{}",+ result_summary: "r1",+ is_write: false,+ is_error: false,+ affected_ids: [],+ });+ db.insertTimelineEntry({+ tool: "create_concept",+ params: "{}",+ result_summary: "r2",+ is_write: true,+ is_error: false,+ affected_ids: ["x"],+ });+ db.insertTimelineEntry({+ tool: "understand",+ params: "{}",+ result_summary: "r3",+ is_write: false,+ is_error: false,+ affected_ids: [],+ });++ const entries = db.getTimelineEntries({ tool: "understand" });+ expect(entries).toHaveLength(2);+ expect(entries.every((e) => e.tool === "understand")).toBe(true);+ expect(entries.map((e) => e.seq)).toEqual([1, 3]);+ });++ it("getTimelineEntries with writesOnly filter works", () => {+ db.insertTimelineEntry({+ tool: "understand",+ params: "{}",+ result_summary: "read",+ is_write: false,+ is_error: false,+ affected_ids: [],+ });+ db.insertTimelineEntry({+ tool: "create_concept",+ params: "{}",+ result_summary: "write1",+ is_write: true,+ is_error: false,+ affected_ids: ["a"],+ });+ db.insertTimelineEntry({+ tool: "link",+ params: "{}",+ result_summary: "write2",+ is_write: true,+ is_error: false,+ affected_ids: ["a", "b"],+ });++ const entries = db.getTimelineEntries({ writesOnly: true });+ expect(entries).toHaveLength(2);+ expect(entries.every((e) => e.is_write === 1)).toBe(true);+ expect(entries.map((e) => e.seq)).toEqual([2, 3]);+ });++ it("getTimelineEntries with since/until time range works", () => {+ const seq1 = db.insertTimelineEntry({+ tool: "t1",+ params: "{}",+ result_summary: "r1",+ is_write: false,+ is_error: false,+ affected_ids: [],+ });+ const seq2 = db.insertTimelineEntry({+ tool: "t2",+ params: "{}",+ result_summary: "r2",+ is_write: true,+ is_error: false,+ affected_ids: ["x"],+ });+ const seq3 = db.insertTimelineEntry({+ tool: "t3",+ params: "{}",+ result_summary: "r3",+ is_write: true,+ is_error: false,+ affected_ids: ["y"],+ });++ setTimelineTimestamp(seq1, "2026-02-10T09:00:00.000Z");+ setTimelineTimestamp(seq2, "2026-02-10T10:00:00.000Z");+ setTimelineTimestamp(seq3, "2026-02-10T11:00:00.000Z");++ const entries = db.getTimelineEntries({+ since: "2026-02-10T09:30:00.000Z",+ until: "2026-02-10T10:30:00.000Z",+ });++ expect(entries).toHaveLength(1);+ expect(entries[0].seq).toBe(seq2);+ expect(entries[0].tool).toBe("t2");+ });+ });++ describe("timeline ticks", () => {+ it("getTimelineTicks(n) returns sampled entries", () => {+ for (let i = 0; i < 10; i += 1) {+ db.insertTimelineEntry({+ tool: `tool-${i}`,+ params: "{}",+ result_summary: `result-${i}`,+ is_write: i % 2 === 0,+ is_error: false,+ affected_ids: [],+ });+ }++ const ticks = db.getTimelineTicks(3);+ expect(ticks.length).toBeGreaterThanOrEqual(3);+ expect(ticks.length).toBeLessThanOrEqual(4);+ expect(ticks[0].seq).toBe(1);+ for (let i = 1; i < ticks.length; i += 1) {+ expect(ticks[i].seq).toBeGreaterThan(ticks[i - 1].seq);+ }+ });++ it("getTimelineTicks returns all entries when n >= total count", () => {+ for (let i = 0; i < 4; i += 1) {+ db.insertTimelineEntry({+ tool: `tool-${i}`,+ params: "{}",+ result_summary: "result",+ is_write: false,+ is_error: false,+ affected_ids: [],+ });+ }++ const ticks = db.getTimelineTicks(10);+ expect(ticks).toHaveLength(4);+ expect(ticks.map((t) => t.seq)).toEqual([1, 2, 3, 4]);+ });+ });++ describe("graph at time", () => {+ beforeEach(() => {+ db.insertNodeRaw({+ id: "node-a",+ name: "Node A",+ kind: "feature",+ summary: "A",+ created_at: "2026-02-10 10:00:00",+ updated_at: "2026-02-10 10:00:00",+ });+ db.insertNodeRaw({+ id: "node-b",+ name: "Node B",+ kind: "feature",+ summary: "B",+ created_at: "2026-02-10 11:00:00",+ updated_at: "2026-02-10 11:00:00",+ });+ db.insertNodeRaw({+ id: "node-c",+ name: "Node C",+ kind: "feature",+ summary: "C",+ created_at: "2026-02-10 12:00:00",+ updated_at: "2026-02-10 12:00:00",+ });+ db.insertNodeRaw({+ id: "node-d",+ name: "Node D",+ kind: "feature",+ summary: "D",+ created_at: "2026-02-10 13:00:00",+ updated_at: "2026-02-10 13:00:00",+ });++ db.softDeleteNode("node-b", "Removed before snapshot");+ db.softDeleteNode("node-c", "Removed after snapshot");+ setNodeRemovedAt("node-b", "2026-02-10 11:30:00");+ setNodeRemovedAt("node-c", "2026-02-10 12:30:00");++ db.insertEdgeRaw({+ from_id: "node-a",+ to_id: "node-c",+ relation: "calls",+ created_at: "2026-02-10 12:00:00",+ });+ db.insertEdgeRaw({+ from_id: "node-a",+ to_id: "node-d",+ relation: "calls",+ created_at: "2026-02-10 12:00:00",+ });+ db.insertEdgeRaw({+ from_id: "node-a",+ to_id: "node-b",+ relation: "calls",+ created_at: "2026-02-10 11:00:00",+ });+ });++ it("getNodesAtTime returns nodes created before the timestamp", () => {+ const nodes = db.getNodesAtTime("2026-02-10 11:15:00");+ const ids = nodes.map((n) => n.id);++ expect(ids).toContain("node-a");+ expect(ids).toContain("node-b");+ });++ it("getNodesAtTime excludes nodes created after the timestamp", () => {+ const nodes = db.getNodesAtTime("2026-02-10 11:15:00");+ const ids = nodes.map((n) => n.id);++ expect(ids).not.toContain("node-c");+ expect(ids).not.toContain("node-d");+ });++ it("getNodesAtTime excludes nodes removed before the timestamp", () => {+ const nodes = db.getNodesAtTime("2026-02-10 12:00:00");+ const ids = nodes.map((n) => n.id);++ expect(ids).not.toContain("node-b");+ });++ it("getNodesAtTime includes nodes removed after the timestamp", () => {+ const nodes = db.getNodesAtTime("2026-02-10 12:00:00");+ const ids = nodes.map((n) => n.id);++ expect(ids).toContain("node-c");+ });++ it("getEdgesAtTime returns edges where both endpoints existed at the timestamp", () => {+ const edges = db.getEdgesAtTime("2026-02-10 12:00:00");+ const pairs = edges.map((e) => `${e.from_id}->${e.to_id}`);++ expect(pairs).toContain("node-a->node-c");+ });++ it("getEdgesAtTime excludes edges where one endpoint was created after the timestamp", () => {+ const edges = db.getEdgesAtTime("2026-02-10 12:00:00");+ const pairs = edges.map((e) => `${e.from_id}->${e.to_id}`);++ expect(pairs).not.toContain("node-a->node-d");+ });++ it("getEdgesAtTime excludes edges where one endpoint was removed before the timestamp", () => {+ const edges = db.getEdgesAtTime("2026-02-10 12:00:00");+ const pairs = edges.map((e) => `${e.from_id}->${e.to_id}`);++ expect(pairs).not.toContain("node-a->node-b");+ });+ });++ describe("schema migration", () => {+ it("verifies schema version is 3", () => {+ const rawDb = new Database(dbPath);+ const pragmaResult = rawDb.pragma("user_version", { simple: true }) as+ | number+ | { user_version: number };+ rawDb.close();++ const version =+ typeof pragmaResult === "object"+ ? pragmaResult.user_version+ : pragmaResult;+ expect(version).toBe(3);+ });++ it("verifies timeline table exists with correct columns", () => {+ const rawDb = new Database(dbPath);+ const columns = rawDb+ .prepare("PRAGMA table_info(timeline)")+ .all() as Array<{ name: string }>;+ rawDb.close();++ const names = columns.map((c) => c.name);+ expect(names).toEqual([+ "seq",+ "timestamp",+ "tool",+ "params",+ "result_summary",+ "is_write",+ "is_error",+ "affected_ids",+ ]);+ });+ });+});diff --git a/src/timeline.ts b/src/timeline.tsnew file mode 100644index 0000000..c3bae5e--- /dev/null+++ b/src/timeline.ts@@ -0,0 +1,32 @@+import type { KnowledgeDB } from "./db.js";++export interface TimelineLogger {+ log(entry: {+ tool: string;+ params: Record<string, unknown>;+ result_summary: string;+ is_write: boolean;+ is_error: boolean;+ affected_ids: string[];+ }): void;+}++export function createTimelineLogger(db: KnowledgeDB): TimelineLogger {+ return {+ log(entry) {+ try {+ db.insertTimelineEntry({+ tool: entry.tool,+ params: JSON.stringify(entry.params),+ result_summary: entry.result_summary,+ is_write: entry.is_write,+ is_error: entry.is_error,+ affected_ids: entry.affected_ids,+ });+ } catch (err) {+ // Timeline logging must never break tool execution+ console.error("Timeline logging failed:", err instanceof Error ? err.message : String(err));+ }+ },+ };+}