engrm 0.1.0

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "engrm",
+  "version": "0.1.0",
+  "description": "Cross-device, team-shared memory layer for AI coding agents",
+  "type": "module",
+  "main": "src/server.ts",
+  "bin": {
+    "engrm": "src/cli.ts"
+  },
+  "scripts": {
+    "start": "bun run src/server.ts",
+    "init": "bun run src/cli.ts init",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@xenova/transformers": "^2.17.2",
+    "sqlite-vec": "^0.1.7-alpha.2"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.19",
+    "typescript": "^5.8.3"
+  },
+  "license": "FSL-1.1-ALv2",
+  "author": "Unimpossible Consultants",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/unimpossible/candengo-mem"
+  }
+}

package/src/capture/dedup.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from "bun:test";
+import { jaccardSimilarity, findDuplicate, DEDUP_THRESHOLD } from "./dedup.js";
+
+describe("jaccardSimilarity", () => {
+  test("identical strings return 1.0", () => {
+    expect(jaccardSimilarity("fix auth bug", "fix auth bug")).toBe(1.0);
+  });
+
+  test("completely different strings return 0.0", () => {
+    expect(jaccardSimilarity("alpha beta gamma", "delta epsilon zeta")).toBe(
+      0.0
+    );
+  });
+
+  test("both empty strings return 1.0", () => {
+    expect(jaccardSimilarity("", "")).toBe(1.0);
+  });
+
+  test("one empty string returns 0.0", () => {
+    expect(jaccardSimilarity("hello", "")).toBe(0.0);
+    expect(jaccardSimilarity("", "hello")).toBe(0.0);
+  });
+
+  test("case insensitive", () => {
+    expect(jaccardSimilarity("Fix Auth Bug", "fix auth bug")).toBe(1.0);
+  });
+
+  test("punctuation stripped", () => {
+    expect(
+      jaccardSimilarity("fix: auth bug!", "fix auth bug")
+    ).toBe(1.0);
+  });
+
+  test("partial overlap returns correct ratio", () => {
+    // "fix auth" vs "fix login" → intersection={fix}, union={fix,auth,login}
+    const sim = jaccardSimilarity("fix auth", "fix login");
+    expect(sim).toBeCloseTo(1 / 3, 5);
+  });
+
+  test("high similarity for near-duplicates", () => {
+    // "fix authentication token refresh bug" vs "fix authentication token refresh issue"
+    // shared: {fix, authentication, token, refresh} = 4
+    // union: {fix, authentication, token, refresh, bug, issue} = 6
+    // Jaccard = 4/6 = 0.667
+    const sim = jaccardSimilarity(
+      "fix authentication token refresh bug",
+      "fix authentication token refresh issue"
+    );
+    expect(sim).toBeCloseTo(4 / 6, 5);
+  });
+
+  test("whitespace-only strings treated as empty", () => {
+    expect(jaccardSimilarity("   ", "   ")).toBe(1.0);
+    expect(jaccardSimilarity("   ", "hello")).toBe(0.0);
+  });
+});
+
+describe("findDuplicate", () => {
+  const candidates = [
+    { id: 1, title: "fix authentication token refresh bug" },
+    { id: 2, title: "add user profile page" },
+    { id: 3, title: "refactor database connection pool" },
+  ];
+
+  test("finds duplicate above threshold", () => {
+    // Candidate 1: "fix authentication token refresh bug"
+    // Query:       "fix authentication token refresh bug typo"
+    // shared: {fix, authentication, token, refresh, bug} = 5
+    // union: {fix, authentication, token, refresh, bug, typo} = 6
+    // Jaccard = 5/6 = 0.833 > 0.8
+    const result = findDuplicate(
+      "fix authentication token refresh bug typo",
+      candidates
+    );
+    expect(result).not.toBeNull();
+    expect(result!.id).toBe(1);
+  });
+
+  test("returns null when no match above threshold", () => {
+    const result = findDuplicate("completely unrelated topic", candidates);
+    expect(result).toBeNull();
+  });
+
+  test("returns null for empty candidates", () => {
+    const result = findDuplicate("anything", []);
+    expect(result).toBeNull();
+  });
+
+  test("returns best match when multiple above threshold", () => {
+    const dupes = [
+      { id: 10, title: "fix auth token bug" },
+      { id: 11, title: "fix auth token bug in refresh" },
+    ];
+    const result = findDuplicate("fix auth token bug in refresh flow", dupes);
+    // Should pick the closer match
+    expect(result).not.toBeNull();
+    expect(result!.id).toBe(11);
+  });
+
+  test("threshold constant is 0.8", () => {
+    expect(DEDUP_THRESHOLD).toBe(0.8);
+  });
+});

package/src/capture/dedup.ts

@@ -0,0 +1,76 @@
+/**
+ * Near-duplicate detection using Jaccard similarity on word tokens.
+ *
+ * From SPEC §2: Before saving a new observation, check title similarity
+ * against last 24h for the same project. If > 0.8, merge into existing.
+ */
+
+/**
+ * Tokenise a string into lowercase word tokens.
+ * Strips punctuation, splits on whitespace.
+ */
+function tokenise(text: string): Set<string> {
+  const cleaned = text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, " ")
+    .trim();
+  const tokens = cleaned.split(/\s+/).filter((t) => t.length > 0);
+  return new Set(tokens);
+}
+
+/**
+ * Compute Jaccard similarity between two strings.
+ * Returns a value between 0.0 (completely different) and 1.0 (identical).
+ *
+ * Jaccard = |A ∩ B| / |A ∪ B|
+ */
+export function jaccardSimilarity(a: string, b: string): number {
+  const tokensA = tokenise(a);
+  const tokensB = tokenise(b);
+
+  if (tokensA.size === 0 && tokensB.size === 0) return 1.0;
+  if (tokensA.size === 0 || tokensB.size === 0) return 0.0;
+
+  let intersectionSize = 0;
+  for (const token of tokensA) {
+    if (tokensB.has(token)) intersectionSize++;
+  }
+
+  const unionSize = tokensA.size + tokensB.size - intersectionSize;
+  if (unionSize === 0) return 0.0;
+
+  return intersectionSize / unionSize;
+}
+
+/**
+ * Similarity threshold for considering two observations as duplicates.
+ * From SPEC §2: title similarity > 0.8 → merge.
+ */
+export const DEDUP_THRESHOLD = 0.8;
+
+export interface DedupCandidate {
+  id: number;
+  title: string;
+}
+
+/**
+ * Find the best matching duplicate from a list of candidates.
+ * Returns the candidate with the highest similarity above threshold, or null.
+ */
+export function findDuplicate(
+  newTitle: string,
+  candidates: DedupCandidate[]
+): DedupCandidate | null {
+  let bestMatch: DedupCandidate | null = null;
+  let bestScore = 0;
+
+  for (const candidate of candidates) {
+    const similarity = jaccardSimilarity(newTitle, candidate.title);
+    if (similarity > DEDUP_THRESHOLD && similarity > bestScore) {
+      bestScore = similarity;
+      bestMatch = candidate;
+    }
+  }
+
+  return bestMatch;
+}

package/src/capture/extractor.test.ts

@@ -0,0 +1,245 @@
+import { describe, expect, test } from "bun:test";
+import { extractObservation, type ToolUseEvent } from "./extractor.js";
+
+function makeEvent(
+  overrides: Partial<ToolUseEvent>
+): ToolUseEvent {
+  return {
+    session_id: "sess-001",
+    hook_event_name: "PostToolUse",
+    tool_name: "Bash",
+    tool_input: {},
+    tool_response: "",
+    cwd: "/tmp/project",
+    ...overrides,
+  };
+}
+
+describe("extractObservation — skip rules", () => {
+  test("skips Read tool", () => {
+    expect(
+      extractObservation(makeEvent({ tool_name: "Read" }))
+    ).toBeNull();
+  });
+
+  test("skips Glob tool", () => {
+    expect(
+      extractObservation(makeEvent({ tool_name: "Glob" }))
+    ).toBeNull();
+  });
+
+  test("skips Grep tool", () => {
+    expect(
+      extractObservation(makeEvent({ tool_name: "Grep" }))
+    ).toBeNull();
+  });
+
+  test("skips WebSearch tool", () => {
+    expect(
+      extractObservation(makeEvent({ tool_name: "WebSearch" }))
+    ).toBeNull();
+  });
+
+  test("skips Agent tool", () => {
+    expect(
+      extractObservation(makeEvent({ tool_name: "Agent" }))
+    ).toBeNull();
+  });
+
+  test("skips navigational bash commands", () => {
+    const commands = ["ls", "pwd", "cd src", "echo hello", "git status", "git log", "node --version"];
+    for (const cmd of commands) {
+      expect(
+        extractObservation(
+          makeEvent({ tool_input: { command: cmd }, tool_response: "output" })
+        )
+      ).toBeNull();
+    }
+  });
+
+  test("skips bash with empty response", () => {
+    expect(
+      extractObservation(
+        makeEvent({ tool_input: { command: "some-cmd" }, tool_response: "" })
+      )
+    ).toBeNull();
+  });
+
+  test("skips engrm MCP tools (self-referential)", () => {
+    expect(
+      extractObservation(
+        makeEvent({
+          tool_name: "mcp__engrm__search",
+          tool_response: "some result that is long enough to normally trigger capture",
+        })
+      )
+    ).toBeNull();
+  });
+});
+
+describe("extractObservation — Edit", () => {
+  test("extracts from file edit", () => {
+    const result = extractObservation(
+      makeEvent({
+        tool_name: "Edit",
+        tool_input: {
+          file_path: "/project/src/auth.ts",
+          old_string: "const token = getToken();",
+          new_string: "const token = await refreshToken();",
+        },
+        tool_response: "Successfully edited",
+      })
+    );
+    expect(result).not.toBeNull();
+    expect(result!.type).toBe("change");
+    expect(result!.title).toContain("auth.ts");
+    expect(result!.files_modified).toEqual(["/project/src/auth.ts"]);
+  });
+
+  test("skips whitespace-only edit", () => {
+    const result = extractObservation(
+      makeEvent({
+        tool_name: "Edit",
+        tool_input: {
+          file_path: "/project/src/app.ts",
+          old_string: "const x = 1;",
+          new_string: "const x = 1; ",
+        },
+        tool_response: "ok",
+      })
+    );
+    expect(result).toBeNull();
+  });
+
+  test("skips edit with no file_path", () => {
+    const result = extractObservation(
+      makeEvent({
+        tool_name: "Edit",
+        tool_input: { old_string: "a", new_string: "b" },
+        tool_response: "ok",
+      })
+    );
+    expect(result).toBeNull();
+  });
+});
+
+describe("extractObservation — Write", () => {
+  test("extracts from file creation", () => {
+    const result = extractObservation(
+      makeEvent({
+        tool_name: "Write",
+        tool_input: {
+          file_path: "/project/src/utils.ts",
+          content: "export function helper() {\n  // substantial content here that is long enough\n  return true;\n}",
+        },
+        tool_response: "File written successfully",
+      })
+    );
+    expect(result).not.toBeNull();
+    expect(result!.type).toBe("change");
+    expect(result!.title).toContain("Created utils.ts");
+    expect(result!.files_modified).toEqual(["/project/src/utils.ts"]);
+  });
+
+  test("skips tiny file writes", () => {
+    const result = extractObservation(
+      makeEvent({
+        tool_name: "Write",
+        tool_input: {
+          file_path: "/project/.gitkeep",
+          content: "",
+        },
+        tool_response: "ok",
+      })
+    );
+    expect(result).toBeNull();
+  });
+});
+
+describe("extractObservation — Bash errors", () => {
+  test("captures error output as bugfix", () => {
+    const result = extractObservation(
+      makeEvent({
+        tool_input: { command: "npm run build" },
+        tool_response:
+          "Error: Cannot find module './missing'\n    at Module._resolveFilename\nexit code 1",
+      })
+    );
+    expect(result).not.toBeNull();
+    expect(result!.type).toBe("bugfix");
+    expect(result!.title).toContain("error");
+  });
+
+  test("captures test failure", () => {
+    const result = extractObservation(
+      makeEvent({
+        tool_input: { command: "bun test" },
+        tool_response: "3 pass\n2 fail\n5 expect() calls",
+      })
+    );
+    expect(result).not.toBeNull();
+    expect(result!.type).toBe("bugfix");
+    expect(result!.title).toContain("Test failure");
+  });
+
+  test("skips passing tests", () => {
+    const result = extractObservation(
+      makeEvent({
+        tool_input: { command: "bun test" },
+        tool_response: "147 pass\n0 fail",
+      })
+    );
+    expect(result).toBeNull();
+  });
+});
+
+describe("extractObservation — Bash dependencies", () => {
+  test("captures npm install", () => {
+    const result = extractObservation(
+      makeEvent({
+        tool_input: { command: "npm install express" },
+        tool_response: "added 57 packages in 3s",
+      })
+    );
+    expect(result).not.toBeNull();
+    expect(result!.type).toBe("change");
+    expect(result!.title).toContain("Dependency change");
+  });
+
+  test("captures bun add", () => {
+    const result = extractObservation(
+      makeEvent({
+        tool_input: { command: "bun add zod" },
+        tool_response: "installed zod@3.22.0",
+      })
+    );
+    expect(result).not.toBeNull();
+    expect(result!.type).toBe("change");
+  });
+});
+
+describe("extractObservation — MCP tools", () => {
+  test("captures non-candengo MCP tool with substantial response", () => {
+    const result = extractObservation(
+      makeEvent({
+        tool_name: "mcp__github__create_pull_request",
+        tool_input: { title: "Fix auth" },
+        tool_response: "a".repeat(150),
+      })
+    );
+    expect(result).not.toBeNull();
+    expect(result!.type).toBe("change");
+    expect(result!.title).toContain("github");
+  });
+
+  test("skips MCP tool with short response", () => {
+    const result = extractObservation(
+      makeEvent({
+        tool_name: "mcp__github__get_issue",
+        tool_input: {},
+        tool_response: "ok",
+      })
+    );
+    expect(result).toBeNull();
+  });
+});