@waynesutton/agent-memory 0.0.1-alpha.1

package/src/cli/index.ts

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import { push, pull, detectTools } from "./sync.js";
+import { extractTypeMemories } from "./type-extractor.js";
+import { ConvexHttpClient } from "convex/browser";
+
+const program = new Command();
+
+program
+  .name("agent-memory")
+  .description(
+    "CLI for syncing agent memories between local files and Convex",
+  )
+  .version("0.0.1");
+
+// ── init ────────────────────────────────────────────────────────────
+
+program
+  .command("init")
+  .description("Detect tools and register project")
+  .option("--project <id>", "Project ID", "default")
+  .option("--name <name>", "Project display name")
+  .action(async (opts) => {
+    const convexUrl = requireConvexUrl();
+    const dir = process.cwd();
+
+    console.log("Detecting tools...");
+    const tools = await detectTools(dir);
+
+    if (tools.length === 0) {
+      console.log(
+        "No tool configurations detected. Supported: Claude Code, Cursor, OpenCode, Codex, Conductor, Zed, VS Code Copilot, Pi",
+      );
+    } else {
+      console.log(`Found: ${tools.join(", ")}`);
+    }
+
+    const client = new ConvexHttpClient(convexUrl);
+    await client.mutation("agentMemory/mutations:upsertProject" as any, {
+      projectId: opts.project,
+      name: opts.name ?? opts.project,
+      settings: {
+        autoSync: false,
+        syncFormats: tools,
+      },
+    });
+
+    console.log(`Project "${opts.project}" registered.`);
+  });
+
+// ── push ────────────────────────────────────────────────────────────
+
+program
+  .command("push")
+  .description("Push local memory files to Convex")
+  .option("--project <id>", "Project ID", "default")
+  .option("--format <format>", "Tool format to parse")
+  .option("--user <id>", "User ID for user-scoped memories")
+  .action(async (opts) => {
+    const convexUrl = requireConvexUrl();
+    console.log("Pushing local memories to Convex...");
+
+    await push({
+      convexUrl,
+      projectId: opts.project,
+      format: opts.format,
+      userId: opts.user,
+      dir: process.cwd(),
+    });
+  });
+
+// ── pull ────────────────────────────────────────────────────────────
+
+program
+  .command("pull")
+  .description("Pull memories from Convex to local files")
+  .option("--project <id>", "Project ID", "default")
+  .option("--format <format>", "Output format", "raw")
+  .option("--user <id>", "User ID for user-scoped memories")
+  .action(async (opts) => {
+    const convexUrl = requireConvexUrl();
+    console.log("Pulling memories from Convex...");
+
+    await pull({
+      convexUrl,
+      projectId: opts.project,
+      format: opts.format,
+      userId: opts.user,
+      dir: process.cwd(),
+    });
+  });
+
+// ── list ────────────────────────────────────────────────────────────
+
+program
+  .command("list")
+  .description("List memories in the terminal")
+  .option("--project <id>", "Project ID", "default")
+  .option("--type <type>", "Filter by memory type")
+  .action(async (opts) => {
+    const convexUrl = requireConvexUrl();
+    const client = new ConvexHttpClient(convexUrl);
+
+    const memories = await client.query(
+      "agentMemory/queries:list" as any,
+      {
+        projectId: opts.project,
+        memoryType: opts.type,
+        archived: false,
+      },
+    );
+
+    if (memories.length === 0) {
+      console.log("No memories found.");
+      return;
+    }
+
+    console.log(`\n${memories.length} memories:\n`);
+    for (const m of memories) {
+      const priority = m.priority !== undefined ? ` [p=${m.priority}]` : "";
+      console.log(
+        `  ${m._id}  ${m.memoryType.padEnd(12)} ${m.title}${priority}`,
+      );
+    }
+  });
+
+// ── search ──────────────────────────────────────────────────────────
+
+program
+  .command("search <query>")
+  .description("Search memories")
+  .option("--project <id>", "Project ID", "default")
+  .option("--limit <n>", "Max results", "10")
+  .action(async (query, opts) => {
+    const convexUrl = requireConvexUrl();
+    const client = new ConvexHttpClient(convexUrl);
+
+    const results = await client.query(
+      "agentMemory/queries:search" as any,
+      {
+        projectId: opts.project,
+        query,
+        limit: parseInt(opts.limit),
+      },
+    );
+
+    if (results.length === 0) {
+      console.log("No results found.");
+      return;
+    }
+
+    console.log(`\n${results.length} results:\n`);
+    for (const m of results) {
+      console.log(`  ${m._id}  ${m.title}`);
+      // Show first 100 chars of content
+      const preview = m.content.slice(0, 100).replace(/\n/g, " ");
+      console.log(`    ${preview}${m.content.length > 100 ? "..." : ""}`);
+      console.log();
+    }
+  });
+
+// ── ingest-types ────────────────────────────────────────────────────
+
+program
+  .command("ingest-types <glob>")
+  .description(
+    "Generate type documentation from TypeScript files and store as reference memories",
+  )
+  .option("--project <id>", "Project ID", "default")
+  .option("--user <id>", "User ID for user-scoped memories")
+  .option("--tags <tags>", "Comma-separated additional tags")
+  .option("--priority <n>", "Priority (0-1)", "0.6")
+  .option(
+    "--exclude <patterns>",
+    "Comma-separated glob patterns to exclude",
+  )
+  .action(async (glob: string, opts) => {
+    const convexUrl = requireConvexUrl();
+
+    console.log(`Extracting types from: ${glob}`);
+
+    const result = await extractTypeMemories({
+      globPattern: glob,
+      cwd: process.cwd(),
+      tags: opts.tags ? opts.tags.split(",") : [],
+      priority: parseFloat(opts.priority),
+      exclude: opts.exclude ? opts.exclude.split(",") : undefined,
+    });
+
+    if (result.memories.length === 0) {
+      console.log(
+        `No exported types found in ${result.filesProcessed} files.`,
+      );
+      return;
+    }
+
+    console.log(
+      `Found ${result.memories.length} type definitions across ${result.filesProcessed} files.`,
+    );
+    console.log("Pushing to Convex...");
+
+    const client = new ConvexHttpClient(convexUrl);
+    const importResult = await client.mutation(
+      "agentMemory/mutations:importFromLocal" as any,
+      {
+        projectId: opts.project,
+        userId: opts.user,
+        memories: result.memories,
+      },
+    );
+
+    console.log(
+      `Done: ${importResult.created} created, ${importResult.updated} updated, ${importResult.unchanged} unchanged`,
+    );
+  });
+
+// ── mcp ─────────────────────────────────────────────────────────────
+
+program
+  .command("mcp")
+  .description("Start the MCP server")
+  .option("--project <id>", "Project ID", "default")
+  .option("--read-only", "Disable write operations")
+  .option("--disable-tools <tools>", "Comma-separated list of tools to disable")
+  .option("--embedding-api-key <key>", "API key for vector search")
+  .action(async (opts) => {
+    const convexUrl = requireConvexUrl();
+    // Dynamic import to avoid loading MCP deps when not needed
+    const { startMcpServer } = await import("../mcp/server.js");
+    await startMcpServer({
+      convexUrl,
+      projectId: opts.project,
+      readOnly: opts.readOnly ?? false,
+      disabledTools: opts.disableTools
+        ? opts.disableTools.split(",")
+        : [],
+      embeddingApiKey: opts.embeddingApiKey,
+    });
+  });
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+function requireConvexUrl(): string {
+  const url = process.env.CONVEX_URL;
+  if (!url) {
+    console.error("Error: CONVEX_URL environment variable is required.");
+    console.error("Set it to your Convex deployment URL.");
+    process.exit(1);
+  }
+  return url;
+}
+
+program.parse();

package/src/cli/parsers/claude-code.ts

@@ -0,0 +1,80 @@
+import { readdir, readFile, access } from "node:fs/promises";
+import { join, basename } from "node:path";
+import matter from "gray-matter";
+import type { Parser, ParsedMemory } from "./types.js";
+import { computeChecksum } from "../../component/checksum.js";
+
+export const claudeCodeParser: Parser = {
+  name: "Claude Code",
+
+  async detect(dir: string): Promise<boolean> {
+    try {
+      await access(join(dir, ".claude"));
+      return true;
+    } catch {
+      return false;
+    }
+  },
+
+  async parse(dir: string): Promise<ParsedMemory[]> {
+    const memories: ParsedMemory[] = [];
+
+    // Parse .claude/rules/*.md
+    const rulesDir = join(dir, ".claude", "rules");
+    const ruleFiles = await safeReaddir(rulesDir);
+    for (const file of ruleFiles) {
+      if (!file.endsWith(".md")) continue;
+      const fullPath = join(rulesDir, file);
+      const raw = await readFile(fullPath, "utf-8");
+      const { data, content } = matter(raw);
+
+      memories.push({
+        title: basename(file, ".md"),
+        content: content.trim(),
+        memoryType: "instruction",
+        scope: "project",
+        tags: [],
+        paths: data.paths as string[] | undefined,
+        priority: 0.9, // rules are high priority
+        source: "claude-code",
+        checksum: computeChecksum(content.trim()),
+      });
+    }
+
+    // Parse memory files from ~/.claude/projects/*/memory/*.md
+    const homeDir = process.env.HOME ?? "";
+    const projectsDir = join(homeDir, ".claude", "projects");
+    const projectDirs = await safeReaddir(projectsDir);
+    for (const projDir of projectDirs) {
+      const memDir = join(projectsDir, projDir, "memory");
+      const memFiles = await safeReaddir(memDir);
+      for (const file of memFiles) {
+        if (!file.endsWith(".md")) continue;
+        const fullPath = join(memDir, file);
+        const raw = await readFile(fullPath, "utf-8");
+        const { data, content } = matter(raw);
+
+        memories.push({
+          title: basename(file, ".md"),
+          content: content.trim(),
+          memoryType: (data.type as string) === "feedback" ? "feedback" : "learning",
+          scope: "user",
+          tags: [],
+          priority: 0.5,
+          source: "claude-code",
+          checksum: computeChecksum(content.trim()),
+        });
+      }
+    }
+
+    return memories;
+  },
+};
+
+async function safeReaddir(dir: string): Promise<string[]> {
+  try {
+    return await readdir(dir);
+  } catch {
+    return [];
+  }
+}

package/src/cli/parsers/codex.ts

@@ -0,0 +1,45 @@
+import { readFile, access } from "node:fs/promises";
+import { join } from "node:path";
+import type { Parser, ParsedMemory } from "./types.js";
+import { computeChecksum } from "../../component/checksum.js";
+
+export const codexParser: Parser = {
+  name: "Codex",
+
+  async detect(dir: string): Promise<boolean> {
+    try {
+      await access(join(dir, "AGENTS.md"));
+      return true;
+    } catch {
+      return false;
+    }
+  },
+
+  async parse(dir: string): Promise<ParsedMemory[]> {
+    const memories: ParsedMemory[] = [];
+
+    // Check AGENTS.override.md first (takes priority)
+    for (const filename of ["AGENTS.override.md", "AGENTS.md"]) {
+      try {
+        const raw = await readFile(join(dir, filename), "utf-8");
+        const content = raw.trim();
+        if (content.length === 0) continue;
+
+        memories.push({
+          title: filename.replace(".md", "").toLowerCase(),
+          content,
+          memoryType: "instruction",
+          scope: "project",
+          tags: [],
+          priority: filename.includes("override") ? 1.0 : 0.8,
+          source: "codex",
+          checksum: computeChecksum(content),
+        });
+      } catch {
+        // File doesn't exist
+      }
+    }
+
+    return memories;
+  },
+};

package/src/cli/parsers/conductor.ts

@@ -0,0 +1,47 @@
+import { readdir, readFile, access } from "node:fs/promises";
+import { join, basename } from "node:path";
+import type { Parser, ParsedMemory } from "./types.js";
+import { computeChecksum } from "../../component/checksum.js";
+
+export const conductorParser: Parser = {
+  name: "Conductor",
+
+  async detect(dir: string): Promise<boolean> {
+    try {
+      await access(join(dir, ".conductor"));
+      return true;
+    } catch {
+      return false;
+    }
+  },
+
+  async parse(dir: string): Promise<ParsedMemory[]> {
+    const memories: ParsedMemory[] = [];
+    const rulesDir = join(dir, ".conductor", "rules");
+
+    let files: string[] = [];
+    try {
+      files = await readdir(rulesDir);
+    } catch {
+      return memories;
+    }
+
+    for (const file of files) {
+      if (!file.endsWith(".md")) continue;
+      const content = (await readFile(join(rulesDir, file), "utf-8")).trim();
+
+      memories.push({
+        title: basename(file, ".md"),
+        content,
+        memoryType: "instruction",
+        scope: "project",
+        tags: [],
+        priority: 0.8,
+        source: "conductor",
+        checksum: computeChecksum(content),
+      });
+    }
+
+    return memories;
+  },
+};

package/src/cli/parsers/cursor.ts

@@ -0,0 +1,55 @@
+import { readdir, readFile, access } from "node:fs/promises";
+import { join, basename } from "node:path";
+import matter from "gray-matter";
+import type { Parser, ParsedMemory } from "./types.js";
+import { computeChecksum } from "../../component/checksum.js";
+
+export const cursorParser: Parser = {
+  name: "Cursor",
+
+  async detect(dir: string): Promise<boolean> {
+    try {
+      await access(join(dir, ".cursor", "rules"));
+      return true;
+    } catch {
+      return false;
+    }
+  },
+
+  async parse(dir: string): Promise<ParsedMemory[]> {
+    const memories: ParsedMemory[] = [];
+    const rulesDir = join(dir, ".cursor", "rules");
+    const files = await safeReaddir(rulesDir);
+
+    for (const file of files) {
+      if (!file.endsWith(".mdc") && !file.endsWith(".md")) continue;
+      const fullPath = join(rulesDir, file);
+      const raw = await readFile(fullPath, "utf-8");
+      const { data, content } = matter(raw);
+
+      const alwaysApply = data.alwaysApply === true;
+
+      memories.push({
+        title: basename(file, file.endsWith(".mdc") ? ".mdc" : ".md"),
+        content: content.trim(),
+        memoryType: "instruction",
+        scope: "project",
+        tags: [],
+        paths: data.paths as string[] | undefined,
+        priority: alwaysApply ? 0.9 : 0.5,
+        source: "cursor",
+        checksum: computeChecksum(content.trim()),
+      });
+    }
+
+    return memories;
+  },
+};
+
+async function safeReaddir(dir: string): Promise<string[]> {
+  try {
+    return await readdir(dir);
+  } catch {
+    return [];
+  }
+}

package/src/cli/parsers/index.ts

@@ -0,0 +1,30 @@
+export type { Parser, ParsedMemory } from "./types.js";
+export { claudeCodeParser } from "./claude-code.js";
+export { cursorParser } from "./cursor.js";
+export { openCodeParser } from "./opencode.js";
+export { codexParser } from "./codex.js";
+export { conductorParser } from "./conductor.js";
+export { zedParser } from "./zed.js";
+export { vscodeCopilotParser } from "./vscode-copilot.js";
+export { piParser } from "./pi.js";
+
+import type { Parser } from "./types.js";
+import { claudeCodeParser } from "./claude-code.js";
+import { cursorParser } from "./cursor.js";
+import { openCodeParser } from "./opencode.js";
+import { codexParser } from "./codex.js";
+import { conductorParser } from "./conductor.js";
+import { zedParser } from "./zed.js";
+import { vscodeCopilotParser } from "./vscode-copilot.js";
+import { piParser } from "./pi.js";
+
+export const ALL_PARSERS: Record<string, Parser> = {
+  "claude-code": claudeCodeParser,
+  cursor: cursorParser,
+  opencode: openCodeParser,
+  codex: codexParser,
+  conductor: conductorParser,
+  zed: zedParser,
+  "vscode-copilot": vscodeCopilotParser,
+  pi: piParser,
+};

package/src/cli/parsers/opencode.ts

@@ -0,0 +1,84 @@
+import { readFile, access } from "node:fs/promises";
+import { join } from "node:path";
+import type { Parser, ParsedMemory } from "./types.js";
+import { computeChecksum } from "../../component/checksum.js";
+
+export const openCodeParser: Parser = {
+  name: "OpenCode",
+
+  async detect(dir: string): Promise<boolean> {
+    try {
+      await access(join(dir, "AGENTS.md"));
+      return true;
+    } catch {
+      return false;
+    }
+  },
+
+  async parse(dir: string): Promise<ParsedMemory[]> {
+    const memories: ParsedMemory[] = [];
+
+    // Parse AGENTS.md — split by ## headings into separate memories
+    try {
+      const raw = await readFile(join(dir, "AGENTS.md"), "utf-8");
+      const sections = splitByHeadings(raw);
+
+      for (const section of sections) {
+        memories.push({
+          title: section.title,
+          content: section.content.trim(),
+          memoryType: "instruction",
+          scope: "project",
+          tags: [],
+          priority: 0.8,
+          source: "opencode",
+          checksum: computeChecksum(section.content.trim()),
+        });
+      }
+    } catch {
+      // AGENTS.md doesn't exist
+    }
+
+    return memories;
+  },
+};
+
+interface Section {
+  title: string;
+  content: string;
+}
+
+function splitByHeadings(markdown: string): Section[] {
+  const lines = markdown.split("\n");
+  const sections: Section[] = [];
+  let currentTitle = "agents-md";
+  let currentContent: string[] = [];
+
+  for (const line of lines) {
+    const match = line.match(/^##\s+(.+)$/);
+    if (match) {
+      if (currentContent.length > 0) {
+        sections.push({
+          title: currentTitle,
+          content: currentContent.join("\n"),
+        });
+      }
+      currentTitle = match[1]
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, "-")
+        .replace(/-+/g, "-");
+      currentContent = [];
+    } else {
+      currentContent.push(line);
+    }
+  }
+
+  if (currentContent.length > 0) {
+    sections.push({
+      title: currentTitle,
+      content: currentContent.join("\n"),
+    });
+  }
+
+  return sections;
+}