@astrocyteai/local 0.1.0

package/tests/context-tree.test.ts

@@ -0,0 +1,209 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { ContextTree } from "../src/context-tree.js";
+
+let tmpDir: string;
+let tree: ContextTree;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "astrocyte-test-"));
+  tree = new ContextTree(tmpDir);
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("ContextTree", () => {
+  describe("store", () => {
+    it("stores a memory and returns a MemoryEntry", () => {
+      const entry = tree.store({
+        content: "Calvin prefers dark mode",
+        bank_id: "test",
+        domain: "preferences",
+        tags: ["ui"],
+      });
+
+      expect(entry.id).toBeTruthy();
+      expect(entry.id.length).toBe(12);
+      expect(entry.bank_id).toBe("test");
+      expect(entry.text).toBe("Calvin prefers dark mode");
+      expect(entry.domain).toBe("preferences");
+      expect(entry.tags).toEqual(["ui"]);
+      expect(entry.memory_layer).toBe("fact");
+      expect(entry.fact_type).toBe("world");
+      expect(entry.recall_count).toBe(0);
+    });
+
+    it("creates markdown file with YAML frontmatter", () => {
+      const entry = tree.store({
+        content: "Test content",
+        bank_id: "test",
+      });
+
+      const fullPath = path.join(tmpDir, "memory", entry.file_path);
+      expect(fs.existsSync(fullPath)).toBe(true);
+
+      const raw = fs.readFileSync(fullPath, "utf-8");
+      expect(raw).toContain("---");
+      expect(raw).toContain(`id: ${entry.id}`);
+      expect(raw).toContain("Test content");
+    });
+
+    it("uses general domain by default", () => {
+      const entry = tree.store({ content: "Hello", bank_id: "test" });
+      expect(entry.domain).toBe("general");
+    });
+
+    it("handles filename collisions", () => {
+      const e1 = tree.store({ content: "Same title", bank_id: "test" });
+      const e2 = tree.store({ content: "Same title", bank_id: "test" });
+
+      expect(e1.file_path).not.toBe(e2.file_path);
+      expect(e1.id).not.toBe(e2.id);
+    });
+
+    it("stores metadata", () => {
+      const entry = tree.store({
+        content: "With metadata",
+        bank_id: "test",
+        metadata: { importance: 5, verified: true },
+      });
+
+      const read = tree.read(entry.id);
+      expect(read).not.toBeNull();
+      expect(read!.metadata.importance).toBe(5);
+      expect(read!.metadata.verified).toBe(true);
+    });
+  });
+
+  describe("read", () => {
+    it("reads an existing entry by ID", () => {
+      const entry = tree.store({ content: "Readable", bank_id: "test" });
+      const read = tree.read(entry.id);
+
+      expect(read).not.toBeNull();
+      expect(read!.id).toBe(entry.id);
+      expect(read!.text).toBe("Readable");
+    });
+
+    it("returns null for non-existent ID", () => {
+      expect(tree.read("nonexistent")).toBeNull();
+    });
+  });
+
+  describe("update", () => {
+    it("updates content of existing entry", () => {
+      const entry = tree.store({ content: "Original", bank_id: "test" });
+      const updated = tree.update(entry.id, "Modified");
+
+      expect(updated).not.toBeNull();
+      expect(updated!.text).toBe("Modified");
+      expect(updated!.updated_at).not.toBe(entry.created_at);
+    });
+
+    it("returns null for non-existent ID", () => {
+      expect(tree.update("nonexistent", "nope")).toBeNull();
+    });
+  });
+
+  describe("delete", () => {
+    it("deletes an existing entry", () => {
+      const entry = tree.store({ content: "Delete me", bank_id: "test" });
+      expect(tree.delete(entry.id)).toBe(true);
+      expect(tree.read(entry.id)).toBeNull();
+    });
+
+    it("returns false for non-existent ID", () => {
+      expect(tree.delete("nonexistent")).toBe(false);
+    });
+
+    it("cleans up empty domain directories", () => {
+      const entry = tree.store({
+        content: "Lonely",
+        bank_id: "test",
+        domain: "temporary",
+      });
+      const domainDir = path.join(tmpDir, "memory", "temporary");
+      expect(fs.existsSync(domainDir)).toBe(true);
+
+      tree.delete(entry.id);
+      expect(fs.existsSync(domainDir)).toBe(false);
+    });
+  });
+
+  describe("recordRecall", () => {
+    it("increments recall count and sets last_recalled_at", () => {
+      const entry = tree.store({ content: "Recalled", bank_id: "test" });
+      expect(entry.recall_count).toBe(0);
+
+      tree.recordRecall(entry.id);
+      const read = tree.read(entry.id);
+      expect(read!.recall_count).toBe(1);
+      expect(read!.last_recalled_at).toBeTruthy();
+    });
+  });
+
+  describe("listDomains", () => {
+    it("lists all domains", () => {
+      tree.store({ content: "A", bank_id: "test", domain: "alpha" });
+      tree.store({ content: "B", bank_id: "test", domain: "beta" });
+
+      const domains = tree.listDomains();
+      expect(domains).toContain("alpha");
+      expect(domains).toContain("beta");
+    });
+
+    it("filters by bank_id", () => {
+      tree.store({ content: "A", bank_id: "bank1", domain: "shared" });
+      tree.store({ content: "B", bank_id: "bank2", domain: "private" });
+
+      const domains = tree.listDomains("bank1");
+      expect(domains).toContain("shared");
+      expect(domains).not.toContain("private");
+    });
+  });
+
+  describe("listEntries", () => {
+    it("lists entries in a domain", () => {
+      tree.store({ content: "One", bank_id: "test", domain: "stuff" });
+      tree.store({ content: "Two", bank_id: "test", domain: "stuff" });
+      tree.store({ content: "Other", bank_id: "test", domain: "other" });
+
+      const entries = tree.listEntries("test", "stuff");
+      expect(entries.length).toBe(2);
+    });
+  });
+
+  describe("scanAll", () => {
+    it("returns all entries", () => {
+      tree.store({ content: "A", bank_id: "test", domain: "x" });
+      tree.store({ content: "B", bank_id: "test", domain: "y" });
+
+      expect(tree.scanAll().length).toBe(2);
+    });
+
+    it("filters by bank_id", () => {
+      tree.store({ content: "A", bank_id: "bank1" });
+      tree.store({ content: "B", bank_id: "bank2" });
+
+      expect(tree.scanAll("bank1").length).toBe(1);
+    });
+  });
+
+  describe("count", () => {
+    it("counts all memories", () => {
+      tree.store({ content: "A", bank_id: "test" });
+      tree.store({ content: "B", bank_id: "test" });
+      expect(tree.count()).toBe(2);
+    });
+
+    it("counts by bank", () => {
+      tree.store({ content: "A", bank_id: "bank1" });
+      tree.store({ content: "B", bank_id: "bank2" });
+      expect(tree.count("bank1")).toBe(1);
+    });
+  });
+});

package/tests/curated-retain.test.ts

@@ -0,0 +1,142 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { parseResponse, curateLocalRetain } from "../src/curated-retain.js";
+import type { LLMProvider } from "../src/curated-retain.js";
+import { ContextTree } from "../src/context-tree.js";
+import { SearchEngine } from "../src/search.js";
+
+describe("parseResponse", () => {
+  it("parses valid JSON", () => {
+    const response =
+      '{"action": "add", "domain": "preferences", "content": "test", "memory_layer": "fact", "reasoning": "new"}';
+    const decision = parseResponse(response, "original");
+    expect(decision.action).toBe("add");
+    expect(decision.domain).toBe("preferences");
+    expect(decision.memory_layer).toBe("fact");
+  });
+
+  it("parses JSON in code block", () => {
+    const response =
+      '```json\n{"action": "merge", "domain": "arch", "content": "merged", "memory_layer": "observation", "reasoning": "similar", "target_id": "abc123"}\n```';
+    const decision = parseResponse(response, "original");
+    expect(decision.action).toBe("merge");
+    expect(decision.target_id).toBe("abc123");
+  });
+
+  it("falls back on invalid JSON", () => {
+    const decision = parseResponse("not json", "original");
+    expect(decision.action).toBe("add");
+    expect(decision.domain).toBe("general");
+    expect(decision.content).toBe("original");
+  });
+
+  it("normalizes domain name", () => {
+    const response =
+      '{"action": "add", "domain": "My Domain / Sub", "content": "test", "memory_layer": "fact", "reasoning": ""}';
+    const decision = parseResponse(response, "original");
+    expect(decision.domain).toBe("my-domain---sub");
+  });
+
+  it("handles skip action", () => {
+    const response =
+      '{"action": "skip", "domain": "", "content": "", "memory_layer": "fact", "reasoning": "redundant"}';
+    const decision = parseResponse(response, "original");
+    expect(decision.action).toBe("skip");
+  });
+
+  it("handles delete action with target_id", () => {
+    const response =
+      '{"action": "delete", "domain": "", "content": "", "memory_layer": "fact", "reasoning": "contradicts", "target_id": "old123"}';
+    const decision = parseResponse(response, "original");
+    expect(decision.action).toBe("delete");
+    expect(decision.target_id).toBe("old123");
+  });
+
+  it("sanitizes invalid action to add", () => {
+    const response =
+      '{"action": "invalid_action", "domain": "test", "content": "test", "memory_layer": "fact", "reasoning": ""}';
+    const decision = parseResponse(response, "original");
+    expect(decision.action).toBe("add");
+  });
+
+  it("sanitizes invalid memory_layer to fact", () => {
+    const response =
+      '{"action": "add", "domain": "test", "content": "test", "memory_layer": "invalid", "reasoning": ""}';
+    const decision = parseResponse(response, "original");
+    expect(decision.memory_layer).toBe("fact");
+  });
+});
+
+describe("curateLocalRetain", () => {
+  let tmpDir: string;
+  let tree: ContextTree;
+  let search: SearchEngine;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "astrocyte-curated-test-"));
+    tree = new ContextTree(tmpDir);
+    search = new SearchEngine(path.join(tmpDir, "_search.db"));
+  });
+
+  afterEach(() => {
+    search.close();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns skip when LLM says skip", async () => {
+    const llm: LLMProvider = {
+      complete: async () => ({
+        text: '{"action": "skip", "domain": "general", "content": "", "memory_layer": "fact", "reasoning": "redundant"}',
+      }),
+    };
+
+    const decision = await curateLocalRetain({
+      content: "redundant info",
+      bankId: "test",
+      tree,
+      search,
+      llmProvider: llm,
+    });
+    expect(decision.action).toBe("skip");
+  });
+
+  it("classifies domain and layer on add", async () => {
+    const llm: LLMProvider = {
+      complete: async () => ({
+        text: '{"action": "add", "domain": "architecture", "content": "PostgreSQL is the primary database", "memory_layer": "fact", "reasoning": "new technical info"}',
+      }),
+    };
+
+    const decision = await curateLocalRetain({
+      content: "We use PostgreSQL",
+      bankId: "test",
+      tree,
+      search,
+      llmProvider: llm,
+    });
+    expect(decision.action).toBe("add");
+    expect(decision.domain).toBe("architecture");
+    expect(decision.memory_layer).toBe("fact");
+  });
+
+  it("falls back to add/general on LLM failure", async () => {
+    const llm: LLMProvider = {
+      complete: async () => {
+        throw new Error("LLM unavailable");
+      },
+    };
+
+    const decision = await curateLocalRetain({
+      content: "should still store",
+      bankId: "test",
+      tree,
+      search,
+      llmProvider: llm,
+    });
+    expect(decision.action).toBe("add");
+    expect(decision.domain).toBe("general");
+    expect(decision.reasoning).toContain("failed");
+  });
+});

package/tests/mcp-server.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { createMcpServer } from "../src/mcp-server.js";
+
+let tmpDir: string;
+let client: Client;
+
+beforeEach(async () => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "astrocyte-mcp-test-"));
+  const mcpServer = createMcpServer({ root: tmpDir, defaultBank: "test" });
+
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  client = new Client({ name: "test-client", version: "1.0.0" });
+
+  await mcpServer.connect(serverTransport);
+  await client.connect(clientTransport);
+});
+
+afterEach(async () => {
+  await client.close();
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("MCP Server", () => {
+  it("lists all tools", async () => {
+    const result = await client.listTools();
+    const names = result.tools.map((t) => t.name);
+
+    expect(names).toContain("memory_retain");
+    expect(names).toContain("memory_recall");
+    expect(names).toContain("memory_browse");
+    expect(names).toContain("memory_forget");
+    expect(names).toContain("memory_banks");
+    expect(names).toContain("memory_health");
+  });
+
+  describe("memory_retain", () => {
+    it("stores content and returns result", async () => {
+      const result = await client.callTool({
+        name: "memory_retain",
+        arguments: {
+          content: "TypeScript is my preferred language",
+          tags: ["preference"],
+        },
+      });
+
+      const text = (result.content as Array<{ type: string; text: string }>)[0].text;
+      const data = JSON.parse(text);
+      expect(data.stored).toBe(true);
+      expect(data.memory_id).toBeTruthy();
+      expect(data.domain).toBe("preference");
+    });
+  });
+
+  describe("memory_recall", () => {
+    it("finds stored memories", async () => {
+      // Store first
+      await client.callTool({
+        name: "memory_retain",
+        arguments: { content: "I prefer vim keybindings" },
+      });
+
+      // Search
+      const result = await client.callTool({
+        name: "memory_recall",
+        arguments: { query: "vim" },
+      });
+
+      const text = (result.content as Array<{ type: string; text: string }>)[0].text;
+      const data = JSON.parse(text);
+      expect(data.total).toBeGreaterThanOrEqual(1);
+      expect(data.hits[0].text).toContain("vim");
+    });
+  });
+
+  describe("memory_browse", () => {
+    it("lists domains at root", async () => {
+      await client.callTool({
+        name: "memory_retain",
+        arguments: { content: "In preferences", domain: "preferences" },
+      });
+
+      const result = await client.callTool({
+        name: "memory_browse",
+        arguments: {},
+      });
+
+      const text = (result.content as Array<{ type: string; text: string }>)[0].text;
+      const data = JSON.parse(text);
+      expect(data.domains).toContain("preferences");
+      expect(data.total_memories).toBeGreaterThanOrEqual(1);
+    });
+
+    it("lists entries in a domain", async () => {
+      await client.callTool({
+        name: "memory_retain",
+        arguments: { content: "Memory in arch", domain: "architecture" },
+      });
+
+      const result = await client.callTool({
+        name: "memory_browse",
+        arguments: { path: "architecture" },
+      });
+
+      const text = (result.content as Array<{ type: string; text: string }>)[0].text;
+      const data = JSON.parse(text);
+      expect(data.entries.length).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  describe("memory_forget", () => {
+    it("deletes memories by ID", async () => {
+      const retainResult = await client.callTool({
+        name: "memory_retain",
+        arguments: { content: "Delete me soon" },
+      });
+      const retainData = JSON.parse(
+        (retainResult.content as Array<{ type: string; text: string }>)[0].text
+      );
+
+      const result = await client.callTool({
+        name: "memory_forget",
+        arguments: { memory_ids: [retainData.memory_id] },
+      });
+
+      const text = (result.content as Array<{ type: string; text: string }>)[0].text;
+      const data = JSON.parse(text);
+      expect(data.deleted_count).toBe(1);
+    });
+  });
+
+  describe("memory_banks", () => {
+    it("lists available banks", async () => {
+      const result = await client.callTool({
+        name: "memory_banks",
+        arguments: {},
+      });
+
+      const text = (result.content as Array<{ type: string; text: string }>)[0].text;
+      const data = JSON.parse(text);
+      expect(data.banks).toContain("test");
+      expect(data.default).toBe("test");
+    });
+  });
+
+  describe("memory_health", () => {
+    it("reports health status", async () => {
+      const result = await client.callTool({
+        name: "memory_health",
+        arguments: {},
+      });
+
+      const text = (result.content as Array<{ type: string; text: string }>)[0].text;
+      const data = JSON.parse(text);
+      expect(data.healthy).toBe(true);
+      expect(data.total_memories).toBeDefined();
+    });
+  });
+});

package/tests/search.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { ContextTree } from "../src/context-tree.js";
+import { SearchEngine } from "../src/search.js";
+
+let tmpDir: string;
+let tree: ContextTree;
+let search: SearchEngine;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "astrocyte-search-test-"));
+  tree = new ContextTree(tmpDir);
+  search = new SearchEngine(path.join(tmpDir, "_search.db"));
+});
+
+afterEach(() => {
+  search.close();
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("SearchEngine", () => {
+  // ── Test Vector 1: Basic keyword match ──
+  describe("basic keyword match", () => {
+    it("finds memories by keyword", () => {
+      const entry = tree.store({
+        content: "Calvin prefers dark mode in all applications",
+        bank_id: "test",
+        tags: ["preference"],
+      });
+      search.addDocument(entry);
+
+      const hits = search.search("dark mode", "test");
+      expect(hits.length).toBeGreaterThanOrEqual(1);
+      expect(hits[0].text).toContain("dark mode");
+    });
+  });
+
+  // ── Test Vector 2: Stemming ──
+  describe("stemming", () => {
+    it("matches stemmed forms (deploy → deployment)", () => {
+      const entry = tree.store({
+        content: "The deploy pipeline uses GitHub Actions",
+        bank_id: "test",
+      });
+      search.addDocument(entry);
+
+      const hits = search.search("deploying", "test");
+      expect(hits.length).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  // ── Test Vector 3: Tag filtering ──
+  describe("tag filtering", () => {
+    it("filters by tags", () => {
+      const a = tree.store({
+        content: "Memory A content",
+        bank_id: "test",
+        tags: ["alpha"],
+      });
+      const b = tree.store({
+        content: "Memory B content",
+        bank_id: "test",
+        tags: ["beta"],
+      });
+      search.addDocument(a);
+      search.addDocument(b);
+
+      const hits = search.search("Memory", "test", { tags: ["alpha"] });
+      expect(hits.length).toBe(1);
+      expect(hits[0].text).toContain("Memory A");
+    });
+  });
+
+  // ── Test Vector 4: Bank isolation ──
+  describe("bank isolation", () => {
+    it("isolates memories by bank", () => {
+      const entry = tree.store({
+        content: "Secret information",
+        bank_id: "bank-1",
+      });
+      search.addDocument(entry);
+
+      const hits = search.search("Secret", "bank-2");
+      expect(hits.length).toBe(0);
+    });
+  });
+
+  // ── Test Vector 5: Wildcard ──
+  describe("wildcard query", () => {
+    it("returns all memories with * query", () => {
+      const a = tree.store({ content: "Memory 1", bank_id: "test" });
+      const b = tree.store({ content: "Memory 2", bank_id: "test" });
+      search.addDocument(a);
+      search.addDocument(b);
+
+      const hits = search.search("*", "test");
+      expect(hits.length).toBe(2);
+    });
+  });
+
+  describe("buildIndex", () => {
+    it("rebuilds index from context tree", () => {
+      tree.store({ content: "Entry one", bank_id: "test" });
+      tree.store({ content: "Entry two", bank_id: "test" });
+
+      const count = search.buildIndex(tree);
+      expect(count).toBe(2);
+
+      const hits = search.search("Entry", "test");
+      expect(hits.length).toBe(2);
+    });
+
+    it("rebuilds for specific bank", () => {
+      tree.store({ content: "Bank A entry", bank_id: "a" });
+      tree.store({ content: "Bank B entry", bank_id: "b" });
+
+      search.buildIndex(tree, "a");
+      const hitsA = search.search("entry", "a");
+      expect(hitsA.length).toBe(1);
+    });
+  });
+
+  describe("addDocument / removeDocument", () => {
+    it("adds and removes documents incrementally", () => {
+      const entry = tree.store({ content: "Temporary", bank_id: "test" });
+      search.addDocument(entry);
+
+      let hits = search.search("Temporary", "test");
+      expect(hits.length).toBe(1);
+
+      search.removeDocument(entry.id);
+      hits = search.search("Temporary", "test");
+      expect(hits.length).toBe(0);
+    });
+  });
+
+  describe("score normalization", () => {
+    it("returns scores between 0 and 1", () => {
+      const a = tree.store({
+        content: "TypeScript is a great programming language",
+        bank_id: "test",
+      });
+      const b = tree.store({
+        content: "Python is also a good language for scripting",
+        bank_id: "test",
+      });
+      search.addDocument(a);
+      search.addDocument(b);
+
+      const hits = search.search("programming language", "test");
+      for (const h of hits) {
+        expect(h.score).toBeGreaterThanOrEqual(0);
+        expect(h.score).toBeLessThanOrEqual(1);
+      }
+    });
+  });
+
+  describe("layer filtering", () => {
+    it("filters by memory layer", () => {
+      const fact = tree.store({
+        content: "A factual memory",
+        bank_id: "test",
+        memory_layer: "fact",
+      });
+      const obs = tree.store({
+        content: "An observed memory",
+        bank_id: "test",
+        memory_layer: "observation",
+      });
+      search.addDocument(fact);
+      search.addDocument(obs);
+
+      const hits = search.search("memory", "test", { layers: ["fact"] });
+      expect(hits.length).toBe(1);
+      expect(hits[0].memory_layer).toBe("fact");
+    });
+  });
+
+  describe("escapeFtsQuery", () => {
+    it("strips special FTS5 characters", () => {
+      expect(SearchEngine.escapeFtsQuery('"hello" (world)')).toBe("hello world");
+      expect(SearchEngine.escapeFtsQuery("test:query")).toBe("test query");
+      expect(SearchEngine.escapeFtsQuery("")).toBe("");
+    });
+  });
+});