claude-code-swarm 0.3.3 → 0.3.5

package/references/minimem/src/session.ts

@@ -0,0 +1,460 @@
+/**
+ * Session tracking for memory entries
+ *
+ * Captures context about the originating session (Claude Code, VS Code, etc.)
+ * and stores it as YAML frontmatter in memory files.
+ */
+
+import * as os from "node:os";
+
+/**
+ * Session metadata for memory entries
+ */
+export type SessionContext = {
+  /** Session identifier (e.g., Claude Code session ID) */
+  id?: string;
+  /** Source application (claude-code, vscode, cursor, etc.) */
+  source?: string;
+  /** Project directory path */
+  project?: string;
+  /** Path to session transcript/log file */
+  transcript?: string;
+};
+
+/**
+ * Source provenance for a knowledge entry
+ */
+export type KnowledgeSource = {
+  origin?: string;
+  trajectories?: string[];
+  agentId?: string;
+};
+
+/**
+ * A directional link from this entry to another knowledge node
+ */
+export type KnowledgeLink = {
+  target: string;
+  relation: string;
+  layer?: string;
+};
+
+/**
+ * Frontmatter structure for memory files
+ */
+export type MemoryFrontmatter = {
+  session?: SessionContext;
+  created?: string;
+  updated?: string;
+  tags?: string[];
+  /** Knowledge node identifier */
+  id?: string;
+  /** Knowledge entry type */
+  type?: "observation" | "entity" | "domain-summary" | string;
+  /** Domain tags for this knowledge entry */
+  domain?: string[];
+  /** Entity references in this knowledge entry */
+  entities?: string[];
+  /** Confidence score 0-1 */
+  confidence?: number;
+  /** Source provenance */
+  source?: KnowledgeSource;
+  /** Links to other knowledge nodes */
+  links?: KnowledgeLink[];
+  /** ID of the entry this supersedes */
+  supersedes?: string | null;
+};
+
+/**
+ * Parse YAML frontmatter from content
+ *
+ * Frontmatter is delimited by --- at the start and end:
+ * ```
+ * ---
+ * session:
+ *   id: abc123
+ *   source: claude-code
+ * created: 2024-01-27T14:30:00Z
+ * ---
+ * Actual content here...
+ * ```
+ */
+export function parseFrontmatter(content: string): {
+  frontmatter: MemoryFrontmatter | undefined;
+  body: string;
+} {
+  const frontmatterRegex = /^---\n([\s\S]*?)\n---\n/;
+  const match = content.match(frontmatterRegex);
+
+  if (!match) {
+    return { frontmatter: undefined, body: content };
+  }
+
+  const yamlContent = match[1];
+  const body = content.slice(match[0].length);
+
+  try {
+    const frontmatter = parseSimpleYaml(yamlContent);
+    return { frontmatter, body };
+  } catch {
+    // If parsing fails, treat as no frontmatter
+    return { frontmatter: undefined, body: content };
+  }
+}
+
+/**
+ * Simple YAML parser for frontmatter.
+ *
+ * **Limitations** (by design — keeps the dependency count at zero):
+ * - Does not handle multi-line strings (block scalars `|` / `>`)
+ * - Does not preserve comments
+ * - Keys must be simple `\w+` identifiers (no quoted or special-char keys)
+ *
+ * Supports:
+ * - Multi-level nesting (objects within objects)
+ * - Inline arrays `[a, b]`
+ * - YAML list items with `- ` syntax (including `- {key: val}` objects)
+ * - Null values via `~` or `null`
+ */
+function parseSimpleYaml(yaml: string): MemoryFrontmatter {
+  const lines = yaml.split("\n");
+  return parseYamlBlock(lines, 0, 0, lines.length).value as MemoryFrontmatter;
+}
+
+/**
+ * Parse a block of YAML lines at a given indentation level into an object.
+ * Returns the parsed value and the line index where parsing stopped.
+ */
+function parseYamlBlock(
+  lines: string[],
+  indent: number,
+  startIdx: number,
+  endIdx: number,
+): { value: Record<string, unknown>; nextIdx: number } {
+  const result: Record<string, unknown> = {};
+  let i = startIdx;
+
+  while (i < endIdx) {
+    const line = lines[i];
+    if (!line || !line.trim()) {
+      i++;
+      continue;
+    }
+
+    const lineIndent = getIndent(line);
+    // If we've dedented back beyond our level, stop
+    if (lineIndent < indent) break;
+    // Skip lines indented deeper than expected (shouldn't happen at top of block)
+    if (lineIndent > indent) {
+      i++;
+      continue;
+    }
+
+    // Match a key: value line
+    const keyMatch = line.match(/^(\s*)([\w-]+):\s*(.*)?$/);
+    if (!keyMatch) {
+      i++;
+      continue;
+    }
+
+    const [, , key, rawValue] = keyMatch;
+    const value = rawValue?.trim() ?? "";
+
+    if (value === "" || value === undefined) {
+      // Could be an object or a list starting on next lines
+      const nextNonEmpty = findNextNonEmptyLine(lines, i + 1, endIdx);
+      if (nextNonEmpty < endIdx) {
+        const nextLine = lines[nextNonEmpty]!;
+        const nextIndent = getIndent(nextLine);
+        if (nextIndent > indent) {
+          // Check if it's a list (starts with "- ")
+          if (nextLine.trimStart().startsWith("- ")) {
+            const listResult = parseYamlList(lines, nextIndent, i + 1, endIdx);
+            result[key] = listResult.value;
+            i = listResult.nextIdx;
+          } else {
+            // Nested object
+            const blockResult = parseYamlBlock(lines, nextIndent, i + 1, endIdx);
+            result[key] = blockResult.value;
+            i = blockResult.nextIdx;
+          }
+          continue;
+        }
+      }
+      // Empty value, no nested content
+      result[key] = null;
+      i++;
+    } else {
+      result[key] = parseYamlValue(value);
+      i++;
+    }
+  }
+
+  return { value: result, nextIdx: i };
+}
+
+/**
+ * Parse a YAML list (lines starting with "- ") at a given indentation level.
+ */
+function parseYamlList(
+  lines: string[],
+  indent: number,
+  startIdx: number,
+  endIdx: number,
+): { value: unknown[]; nextIdx: number } {
+  const result: unknown[] = [];
+  let i = startIdx;
+
+  while (i < endIdx) {
+    const line = lines[i];
+    if (!line || !line.trim()) {
+      i++;
+      continue;
+    }
+
+    const lineIndent = getIndent(line);
+    if (lineIndent < indent) break;
+    if (lineIndent > indent) {
+      i++;
+      continue;
+    }
+
+    const trimmed = line.trimStart();
+    if (!trimmed.startsWith("- ")) break;
+
+    // Get content after "- "
+    const itemContent = trimmed.slice(2).trim();
+
+    if (itemContent === "" || itemContent === undefined) {
+      // Sub-block under this list item
+      const nextNonEmpty = findNextNonEmptyLine(lines, i + 1, endIdx);
+      if (nextNonEmpty < endIdx) {
+        const nextIndent = getIndent(lines[nextNonEmpty]!);
+        if (nextIndent > indent) {
+          const blockResult = parseYamlBlock(lines, nextIndent, i + 1, endIdx);
+          result.push(blockResult.value);
+          i = blockResult.nextIdx;
+          continue;
+        }
+      }
+      result.push(null);
+      i++;
+    } else {
+      // Check for inline key: value (object item like "- target: foo")
+      const kvMatch = itemContent.match(/^([\w-]+):\s*(.*)$/);
+      if (kvMatch) {
+        // This list item is an object — collect all keys at this item's indent + 2
+        const obj: Record<string, unknown> = {};
+        const [, firstKey, firstVal] = kvMatch;
+        obj[firstKey] = parseYamlValue(firstVal?.trim() ?? "");
+
+        // Look for continuation keys indented further
+        const itemKeyIndent = indent + 2;
+        let j = i + 1;
+        while (j < endIdx) {
+          const nextLine = lines[j];
+          if (!nextLine || !nextLine.trim()) {
+            j++;
+            continue;
+          }
+          const nextLineIndent = getIndent(nextLine);
+          if (nextLineIndent < itemKeyIndent) break;
+          if (nextLineIndent === itemKeyIndent) {
+            const nextKv = nextLine.match(/^\s*([\w-]+):\s*(.*)$/);
+            if (nextKv) {
+              const [, nk, nv] = nextKv;
+              obj[nk] = parseYamlValue(nv?.trim() ?? "");
+              j++;
+              continue;
+            }
+          }
+          break;
+        }
+        result.push(obj);
+        i = j;
+      } else {
+        result.push(parseYamlValue(itemContent));
+        i++;
+      }
+    }
+  }
+
+  return { value: result, nextIdx: i };
+}
+
+function getIndent(line: string): number {
+  const match = line.match(/^(\s*)/);
+  return match ? match[1].length : 0;
+}
+
+function findNextNonEmptyLine(lines: string[], from: number, end: number): number {
+  for (let i = from; i < end; i++) {
+    if (lines[i]?.trim()) return i;
+  }
+  return end;
+}
+
+/**
+ * Parse a YAML value (handles strings, numbers, booleans, null, arrays)
+ */
+function parseYamlValue(value: string): unknown {
+  // Empty string
+  if (value === "") return null;
+
+  // Remove quotes if present
+  if ((value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))) {
+    return value.slice(1, -1);
+  }
+
+  // Null
+  if (value === "null" || value === "~") return null;
+
+  // Boolean
+  if (value === "true") return true;
+  if (value === "false") return false;
+
+  // Number
+  const num = Number(value);
+  if (!isNaN(num) && value !== "") return num;
+
+  // Array (simple inline format)
+  if (value.startsWith("[") && value.endsWith("]")) {
+    const inner = value.slice(1, -1);
+    if (inner.trim() === "") return [];
+    return inner.split(",").map((s) => parseYamlValue(s.trim()));
+  }
+
+  // String
+  return value;
+}
+
+/**
+ * Serialize frontmatter to YAML string
+ */
+export function serializeFrontmatter(frontmatter: MemoryFrontmatter): string {
+  const lines: string[] = ["---"];
+
+  if (frontmatter.id) {
+    lines.push(`id: ${frontmatter.id}`);
+  }
+
+  if (frontmatter.type) {
+    lines.push(`type: ${frontmatter.type}`);
+  }
+
+  if (frontmatter.session) {
+    lines.push("session:");
+    const session = frontmatter.session;
+    if (session.id) lines.push(`  id: ${session.id}`);
+    if (session.source) lines.push(`  source: ${session.source}`);
+    if (session.project) lines.push(`  project: ${formatPath(session.project)}`);
+    if (session.transcript) lines.push(`  transcript: ${formatPath(session.transcript)}`);
+  }
+
+  if (frontmatter.created) {
+    lines.push(`created: ${frontmatter.created}`);
+  }
+
+  if (frontmatter.updated) {
+    lines.push(`updated: ${frontmatter.updated}`);
+  }
+
+  if (frontmatter.tags && frontmatter.tags.length > 0) {
+    lines.push(`tags: [${frontmatter.tags.join(", ")}]`);
+  }
+
+  if (frontmatter.domain && frontmatter.domain.length > 0) {
+    lines.push(`domain: [${frontmatter.domain.join(", ")}]`);
+  }
+
+  if (frontmatter.entities && frontmatter.entities.length > 0) {
+    lines.push(`entities: [${frontmatter.entities.join(", ")}]`);
+  }
+
+  if (frontmatter.confidence !== undefined) {
+    lines.push(`confidence: ${frontmatter.confidence}`);
+  }
+
+  if (frontmatter.source) {
+    lines.push("source:");
+    if (frontmatter.source.origin) lines.push(`  origin: ${frontmatter.source.origin}`);
+    if (frontmatter.source.trajectories && frontmatter.source.trajectories.length > 0) {
+      lines.push(`  trajectories: [${frontmatter.source.trajectories.join(", ")}]`);
+    }
+    if (frontmatter.source.agentId) lines.push(`  agentId: ${frontmatter.source.agentId}`);
+  }
+
+  if (frontmatter.links && frontmatter.links.length > 0) {
+    lines.push("links:");
+    for (const link of frontmatter.links) {
+      lines.push(`  - target: ${link.target}`);
+      lines.push(`    relation: ${link.relation}`);
+      if (link.layer) lines.push(`    layer: ${link.layer}`);
+    }
+  }
+
+  if (frontmatter.supersedes !== undefined) {
+    lines.push(`supersedes: ${frontmatter.supersedes === null ? "~" : frontmatter.supersedes}`);
+  }
+
+  lines.push("---");
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Add or update frontmatter in content
+ */
+export function addFrontmatter(
+  content: string,
+  frontmatter: MemoryFrontmatter,
+): string {
+  const { frontmatter: existing, body } = parseFrontmatter(content);
+
+  // Merge with existing frontmatter
+  const merged: MemoryFrontmatter = {
+    ...existing,
+    ...frontmatter,
+    session: {
+      ...existing?.session,
+      ...frontmatter.session,
+    },
+  };
+
+  // Update timestamp
+  if (!merged.created) {
+    merged.created = new Date().toISOString();
+  }
+  merged.updated = new Date().toISOString();
+
+  return serializeFrontmatter(merged) + body;
+}
+
+/**
+ * Add session context as frontmatter to content
+ */
+export function addSessionToContent(
+  content: string,
+  session: SessionContext,
+): string {
+  return addFrontmatter(content, { session });
+}
+
+/**
+ * Format path for display (use ~ for home directory)
+ */
+function formatPath(filePath: string): string {
+  const home = os.homedir();
+  if (filePath.startsWith(home)) {
+    return "~" + filePath.slice(home.length);
+  }
+  return filePath;
+}
+
+/**
+ * Extract session context from file content
+ */
+export function extractSession(content: string): SessionContext | undefined {
+  const { frontmatter } = parseFrontmatter(content);
+  return frontmatter?.session;
+}

package/references/minimem/src/store/__tests__/manifest.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, it, beforeEach, afterEach } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+
+import {
+  loadManifest,
+  saveManifest,
+  loadStoreLinks,
+  saveStoreLinks,
+  resolveStore,
+  resolveStoreName,
+  getLinkedStoreNames,
+  type StoreManifest,
+} from "../manifest.js";
+
+describe("manifest", () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "minimem-manifest-test-"));
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  describe("loadManifest / saveManifest", () => {
+    it("returns empty manifest when file does not exist", async () => {
+      const manifest = await loadManifest(path.join(tmpDir, "nonexistent.json"));
+      expect(manifest.stores).toEqual({});
+    });
+
+    it("round-trips a manifest", async () => {
+      const manifestPath = path.join(tmpDir, "stores.json");
+      const manifest: StoreManifest = {
+        stores: {
+          "project-a": { path: "/home/user/project-a" },
+          "project-b": {
+            path: "/home/user/project-b",
+            remote: "git@github.com:org/project-b.git",
+            description: "Project B memories",
+          },
+        },
+      };
+
+      await saveManifest(manifest, manifestPath);
+      const loaded = await loadManifest(manifestPath);
+
+      expect(loaded.stores["project-a"].path).toBe("/home/user/project-a");
+      expect(loaded.stores["project-b"].remote).toBe("git@github.com:org/project-b.git");
+      expect(loaded.stores["project-b"].description).toBe("Project B memories");
+    });
+
+    it("expands ~ in paths", async () => {
+      const manifestPath = path.join(tmpDir, "stores.json");
+      await fs.writeFile(
+        manifestPath,
+        JSON.stringify({ stores: { test: { path: "~/my-project" } } }),
+      );
+
+      const loaded = await loadManifest(manifestPath);
+      expect(loaded.stores["test"].path).toBe(
+        path.join(os.homedir(), "my-project"),
+      );
+    });
+  });
+
+  describe("loadStoreLinks / saveStoreLinks", () => {
+    it("returns empty links when no file exists", async () => {
+      const links = await loadStoreLinks(tmpDir);
+      expect(links.links).toEqual([]);
+    });
+
+    it("loads links from .minimem/links.json", async () => {
+      const linksDir = path.join(tmpDir, ".minimem");
+      await fs.mkdir(linksDir, { recursive: true });
+      await fs.writeFile(
+        path.join(linksDir, "links.json"),
+        JSON.stringify({ links: ["project-a", "project-b"] }),
+      );
+
+      const links = await loadStoreLinks(tmpDir);
+      expect(links.links).toEqual(["project-a", "project-b"]);
+    });
+
+    it("saves links to existing config dir", async () => {
+      const linksDir = path.join(tmpDir, ".minimem");
+      await fs.mkdir(linksDir, { recursive: true });
+
+      await saveStoreLinks(tmpDir, { links: ["store-x"] });
+
+      const content = await fs.readFile(
+        path.join(linksDir, "links.json"),
+        "utf-8",
+      );
+      expect(JSON.parse(content).links).toEqual(["store-x"]);
+    });
+  });
+
+  describe("resolveStore", () => {
+    it("returns store definition by name", () => {
+      const manifest: StoreManifest = {
+        stores: { mystore: { path: "/tmp/mystore" } },
+      };
+      const def = resolveStore(manifest, "mystore");
+      expect(def).not.toBeNull();
+      expect(def!.path).toBe("/tmp/mystore");
+    });
+
+    it("returns null for unknown store", () => {
+      const manifest: StoreManifest = { stores: {} };
+      expect(resolveStore(manifest, "missing")).toBeNull();
+    });
+  });
+
+  describe("resolveStoreName", () => {
+    it("finds store name by path", () => {
+      const manifest: StoreManifest = {
+        stores: { mystore: { path: "/tmp/mystore" } },
+      };
+      expect(resolveStoreName(manifest, "/tmp/mystore")).toBe("mystore");
+    });
+
+    it("returns null for unregistered path", () => {
+      const manifest: StoreManifest = { stores: {} };
+      expect(resolveStoreName(manifest, "/tmp/unknown")).toBeNull();
+    });
+  });
+
+  describe("getLinkedStoreNames", () => {
+    it("returns linked store names from per-store links", async () => {
+      // Create a store dir with links
+      const storeDir = path.join(tmpDir, "my-store");
+      const linksDir = path.join(storeDir, ".minimem");
+      await fs.mkdir(linksDir, { recursive: true });
+      await fs.writeFile(
+        path.join(linksDir, "links.json"),
+        JSON.stringify({ links: ["dep-a", "dep-b"] }),
+      );
+
+      const manifest: StoreManifest = {
+        stores: {
+          "my-store": { path: storeDir },
+          "dep-a": { path: "/tmp/dep-a" },
+          "dep-b": { path: "/tmp/dep-b" },
+        },
+      };
+
+      const linked = await getLinkedStoreNames(manifest, "my-store");
+      expect(linked).toEqual(["dep-a", "dep-b"]);
+    });
+
+    it("returns empty for store not in manifest", async () => {
+      const manifest: StoreManifest = { stores: {} };
+      const linked = await getLinkedStoreNames(manifest, "missing");
+      expect(linked).toEqual([]);
+    });
+
+    it("deduplicates linked stores", async () => {
+      const storeDir = path.join(tmpDir, "my-store");
+      const linksDir = path.join(storeDir, ".minimem");
+      await fs.mkdir(linksDir, { recursive: true });
+      await fs.writeFile(
+        path.join(linksDir, "links.json"),
+        JSON.stringify({ links: ["dep-a", "dep-a", "dep-b"] }),
+      );
+
+      const manifest: StoreManifest = {
+        stores: { "my-store": { path: storeDir } },
+      };
+
+      const linked = await getLinkedStoreNames(manifest, "my-store");
+      expect(linked).toEqual(["dep-a", "dep-b"]);
+    });
+  });
+});

package/references/minimem/src/store/__tests__/materialize.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it, beforeEach, afterEach } from "vitest";
+import fs from "node:fs/promises";
+import fsSync from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+import { materializeStore, type MaterializeResult } from "../materialize.js";
+
+describe("materializeStore", () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "minimem-materialize-test-"));
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns symlink strategy for existing local store", async () => {
+    const storePath = path.join(tmpDir, "my-store");
+    await fs.mkdir(storePath, { recursive: true });
+    await fs.writeFile(path.join(storePath, "MEMORY.md"), "# Memory\n");
+
+    const result = await materializeStore("my-store", { path: storePath });
+
+    expect(result).not.toBeNull();
+    expect(result!.strategy).toBe("symlink");
+    expect(result!.path).toBe(storePath);
+
+    // Cleanup should work without error
+    await result!.cleanup();
+  });
+
+  it("returns null for nonexistent store with no remote", async () => {
+    const result = await materializeStore("missing", {
+      path: "/nonexistent/path",
+    });
+    expect(result).toBeNull();
+  });
+
+  it("symlink cleanup removes temp dir", async () => {
+    const storePath = path.join(tmpDir, "my-store");
+    await fs.mkdir(storePath, { recursive: true });
+
+    const result = await materializeStore("my-store", { path: storePath });
+    expect(result).not.toBeNull();
+
+    // The cleanup function should not throw
+    await result!.cleanup();
+  });
+});