ctxcarry 0.3.0

package/README.md

@@ -0,0 +1,239 @@
+<div align="center">
+
+<p>
+  <img src="./assets/ctxcarry-ascii.svg" alt="ctxcarry - Portable project memory for AI coding agents" width="100%">
+</p>
+
+<h2>Move work between Claude Code, Codex, and future agents without losing repo state.</h2>
+
+<p>
+  <img src="https://img.shields.io/badge/build-passing-22c55e?style=flat-square" />
+  <img src="https://img.shields.io/badge/version-v0.3.0-f97316?style=flat-square" />
+  <img src="https://img.shields.io/badge/npm-ctxcarry-c026d3?style=flat-square" />
+  <img src="https://img.shields.io/badge/node-%3E%3D20-3b82f6?style=flat-square" />
+  <img src="https://img.shields.io/badge/license-MIT-8b5cf6?style=flat-square" />
+  <img src="https://img.shields.io/badge/local--first-yes-111827?style=flat-square" />
+</p>
+
+<p>
+  <a href="#quickstart">Quickstart</a> ·
+  <a href="#commands">Commands</a> ·
+  <a href="#mcp-retrieval">MCP</a> ·
+  <a href="#benchmarks">Benchmarks</a> ·
+  <a href="./BENCHMARKS.md">Proof</a> ·
+  <a href="#development">Development</a>
+</p>
+
+<p>
+  <strong>AI agents / LLMs:</strong> use ctxcarry to capture repo state, compact session memory, and continue work across agents.
+</p>
+
+</div>
+
+---
+
+# ctxcarry
+
+**Portable project memory for AI coding agents.**
+
+ctxcarry lets developers move long-running coding work between Claude Code, Codex, and future agents without losing the working state of a repo. It captures what happened in an agent session, distills the useful state, and generates the right handoff context for the next agent.
+
+The core idea:
+
+> Coding agents should not own your context. Your repo should.
+
+## Why
+
+AI coding agents are powerful, but their context is trapped inside isolated sessions. If you start in Claude Code and then switch to Codex, the next agent usually does not know:
+
+- what task was in progress
+- which files changed
+- what tests failed
+- what decisions were made
+- what constraints matter
+- what the next step should be
+
+ctxcarry stores that state locally in your repository and compiles compact agent-specific context files.
+
+## Quickstart
+
+```bash
+npm install -g ctxcarry
+```
+
+Inside a project:
+
+```bash
+ctxcarry init
+ctxcarry run claude
+ctxcarry switch codex
+codex
+```
+
+That creates a Claude session, captures before/after git state, asks Claude to write a structured summary, compacts the result, updates `AGENTS.md`, and prepares Codex to continue.
+
+## What It Generates
+
+ctxcarry stores source-of-truth state under `.ctxcarry/`:
+
+```text
+.ctxcarry/
+  events.jsonl
+  commands.jsonl
+  state.json
+  state.md
+  learned.md
+  sessions/
+  ctxcarrys/
+    codex.md
+    claude.md
+```
+
+Generated agent files:
+
+- `AGENTS.md` for Codex
+- `CLAUDE.md` for Claude Code
+- `.ctxcarry/ctxcarrys/codex.md`
+- `.ctxcarry/ctxcarrys/claude.md`
+
+## Commands
+
+```bash
+ctxcarry init
+ctxcarry run claude
+ctxcarry switch codex
+ctxcarry status
+```
+
+Useful extras:
+
+```bash
+ctxcarry capture
+ctxcarry compact
+ctxcarry compile --agent codex
+ctxcarry compile --agent claude
+handoff tokens
+```
+
+Add explicit context when needed:
+
+```bash
+ctxcarry note --type task --text "Fix Google OAuth redirect bug"
+ctxcarry note --type decision --text "Do not rewrite the auth provider"
+ctxcarry note --type constraint --text "Preserve existing email login behavior"
+ctxcarry note --type failure --text "Production callback returns 400"
+ctxcarry note --type next --text "Check redirect URI construction"
+```
+
+## Session Summaries
+
+Before launching an agent, ctxcarry writes:
+
+```text
+.ctxcarry/sessions/<session-id>/instructions.md
+```
+
+The instruction asks the agent to write:
+
+```text
+.ctxcarry/sessions/<session-id>/summary.md
+```
+
+with strict headings:
+
+```md
+## Current Task
+## Files Changed
+## Decisions
+## Constraints
+## Failures
+## Commands Run
+## Next Step
+```
+
+If the summary exists, ctxcarry parses it into structured memory. If it does not, ctxcarry falls back to git snapshots, changed files, branch, and diff summary.
+
+## MCP Retrieval
+
+Serve local project memory to MCP-compatible clients:
+
+```bash
+ctxcarry mcp serve
+```
+
+Available tools:
+
+- `get_current_task`
+- `get_latest_ctxcarry`
+- `get_relevant_session_events`
+- `expand_session_artifact`
+- `summarize_latest_failure`
+
+## Learning
+
+Mine local sessions for durable guidance:
+
+```bash
+ctxcarry learn
+ctxcarry learn --apply
+```
+
+`--apply` writes `.ctxcarry/learned.md` and updates `AGENTS.md` / `CLAUDE.md` with learned guidance.
+
+## Benchmarks
+
+Run deterministic local fixture benchmarks:
+
+```bash
+pnpm run bench
+pnpm run bench -- --format json
+pnpm run bench -- --out BENCHMARKS.md
+```
+
+Current synthetic/local fixture headline:
+
+| Metric | Value |
+| --- | ---: |
+| Total raw benchmark tokens | 210,371 |
+| Total handoff tokens | 2,053 |
+| Total saved tokens | 208,324 |
+| Overall compression | 99.0% |
+| Mean critical-fact recall | 100.0% |
+| Mean budget recall | 100.0% |
+| Contradictions found | 0 |
+| Redaction checks | PASS |
+
+These are deterministic synthetic/local fixture benchmarks, not production telemetry or real agent-execution results.
+
+Run benchmarks on real local sessions:
+
+```bash
+pnpm run bench:real -- --project /path/to/your/project
+pnpm run bench:continuation -- --project /path/to/your/project
+```
+
+Real-session benchmarks report observable local artifacts only. They do not fabricate task-success or recall metrics.
+
+## Development
+
+```bash
+pnpm install
+pnpm run build
+pnpm test
+pnpm run bench
+```
+
+Link locally:
+
+```bash
+pnpm link --global
+ctxcarry --help
+```
+
+## Status
+
+ctxcarry is early local-first developer tooling. The current focus is reliable Claude Code to Codex handoff, local session capture, compact project memory, and measurable benchmark quality.
+
+## License
+
+MIT

package/assets/ctxcarry-ascii.svg

@@ -0,0 +1,39 @@
+<svg width="1400" height="300" viewBox="0 0 1400 300" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="ctxcarryGradient" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#22c55e"/>
+      <stop offset="35%" stop-color="#38bdf8"/>
+      <stop offset="70%" stop-color="#8b5cf6"/>
+      <stop offset="100%" stop-color="#f97316"/>
+    </linearGradient>
+  </defs>
+
+  <rect width="1400" height="300" rx="18" fill="#0d1117"/>
+
+  <text
+    x="220"
+    y="60"
+    font-family="Consolas, Monaco, 'Courier New', monospace"
+    font-size="24"
+    font-weight="800"
+    fill="url(#ctxcarryGradient)"
+    xml:space="preserve">
+    <tspan x="220" dy="0"> ██████╗████████╗██╗  ██╗ ██████╗ █████╗ ██████╗ ██████╗ ██╗   ██╗</tspan>
+    <tspan x="220" dy="34">██╔════╝╚══██╔══╝╚██╗██╔╝██╔════╝██╔══██╗██╔══██╗██╔══██╗╚██╗ ██╔╝</tspan>
+    <tspan x="220" dy="34">██║        ██║    ╚███╔╝ ██║     ███████║██████╔╝██████╔╝ ╚████╔╝ </tspan>
+    <tspan x="220" dy="34">██║        ██║    ██╔██╗ ██║     ██╔══██║██╔══██╗██╔══██╗  ╚██╔╝  </tspan>
+    <tspan x="220" dy="34">╚██████╗   ██║   ██╔╝ ██╗╚██████╗██║  ██║██║  ██║██║  ██║   ██║   </tspan>
+    <tspan x="220" dy="34"> ╚═════╝   ╚═╝   ╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝   </tspan>
+  </text>
+
+  <text
+    x="700"
+    y="265"
+    text-anchor="middle"
+    font-family="Consolas, Monaco, 'Courier New', monospace"
+    font-size="24"
+    font-weight="600"
+    fill="#e6edf3">
+    Portable project memory for AI coding agents
+  </text>
+</svg>

package/dist/archive.js

@@ -0,0 +1,19 @@
+import fs from "node:fs";
+import path from "node:path";
+import { redactText } from "./redact.js";
+import { routeContent } from "./content-router.js";
+export function archiveSessionArtifact(sessionDir, name, content) {
+    const rawDir = path.join(sessionDir, "raw");
+    fs.mkdirSync(rawDir, { recursive: true });
+    const artifactId = name.replace(/[^a-z0-9_.-]/gi, "-").toLowerCase();
+    const artifactPath = path.join(rawDir, artifactId);
+    const redacted = redactText(content);
+    fs.writeFileSync(artifactPath, redacted.endsWith("\n") ? redacted : `${redacted}\n`);
+    const routed = routeContent(name, redacted);
+    return {
+        artifactId,
+        path: artifactPath,
+        kind: routed.kind,
+        summary: routed.summary
+    };
+}

package/dist/capture.js

@@ -0,0 +1,250 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { archiveSessionArtifact } from "./archive.js";
+import { ctxcarryPath } from "./paths.js";
+import { redactText } from "./redact.js";
+import { appendEvent, readConfig } from "./store.js";
+import { getGitSnapshot, summarizeSnapshot } from "./git.js";
+export function captureSnapshot(agent) {
+    const snapshot = getGitSnapshot();
+    appendEvent({
+        type: "repo_snapshot",
+        agent,
+        branch: snapshot.branch,
+        isRepo: snapshot.isRepo,
+        status: snapshot.status,
+        changedFiles: snapshot.changedFiles,
+        diffStat: snapshot.diffStat,
+        summary: summarizeSnapshot(snapshot)
+    });
+    return snapshot;
+}
+export async function runAgent(agent) {
+    const config = readConfig();
+    const agentConfig = config.agents[agent];
+    if (!agentConfig?.enabled) {
+        throw new Error(`Agent "${agent}" is not enabled in ctxcarry.config.json.`);
+    }
+    const sessionId = createSessionId(agent);
+    const sessionDir = ctxcarryPath("sessions", sessionId);
+    fs.mkdirSync(sessionDir, { recursive: true });
+    const instructionsPath = path.join(sessionDir, "instructions.md");
+    const summaryPath = path.join(sessionDir, "summary.md");
+    writeSessionInstructions(agent, sessionId, instructionsPath, summaryPath);
+    const instructionArtifact = archiveSessionArtifact(sessionDir, "instructions.md", fs.readFileSync(instructionsPath, "utf8"));
+    const command = agentConfig.command ?? agent;
+    const startedAtMs = Date.now();
+    const startedAt = new Date(startedAtMs).toISOString();
+    const before = getGitSnapshot();
+    writeSnapshot(sessionDir, "before", before);
+    appendEvent({
+        type: "session_started",
+        agent,
+        sessionId,
+        sessionDir,
+        instructionsPath,
+        summaryPath,
+        command,
+        startedAt,
+        instructionArtifact,
+        branch: before.branch,
+        changedFiles: before.changedFiles,
+        diffStat: before.diffStat
+    });
+    const exitCode = await spawnInteractive(command, sessionDir, instructionsPath, summaryPath);
+    const endedAtMs = Date.now();
+    const endedAt = new Date(endedAtMs).toISOString();
+    const after = getGitSnapshot();
+    writeSnapshot(sessionDir, "after", after);
+    const beforeArtifact = archiveSessionArtifact(sessionDir, "before.json", JSON.stringify(before, null, 2));
+    const afterArtifact = archiveSessionArtifact(sessionDir, "after.json", JSON.stringify(after, null, 2));
+    const changedFiles = unique([...before.changedFiles, ...after.changedFiles]);
+    const newFiles = statusFiles(after.status, ["??", "A", "AM"]);
+    const deletedFiles = statusFiles(after.status, ["D", "AD"]);
+    const durationMs = endedAtMs - startedAtMs;
+    appendEvent({
+        type: "repo_snapshot",
+        agent,
+        sessionId,
+        branch: after.branch,
+        isRepo: after.isRepo,
+        status: after.status,
+        changedFiles,
+        newFiles,
+        deletedFiles,
+        diffStat: after.diffStat,
+        summary: summarizeSnapshot(after)
+    });
+    appendEvent({
+        type: "agent_session",
+        agent,
+        sessionId,
+        sessionDir,
+        instructionsPath,
+        summaryPath,
+        command,
+        startedAt,
+        endedAt,
+        durationMs,
+        exitCode,
+        branch: after.branch,
+        before,
+        after,
+        changedFiles,
+        newFiles,
+        deletedFiles,
+        diffSummary: after.diffStat
+    });
+    appendEvent({
+        type: "session_artifacts",
+        agent,
+        sessionId,
+        artifacts: [instructionArtifact, beforeArtifact, afterArtifact]
+    });
+    if (fs.existsSync(summaryPath)) {
+        const summaryArtifact = archiveSessionArtifact(sessionDir, "summary.md", fs.readFileSync(summaryPath, "utf8"));
+        appendEvent({
+            type: "session_artifact",
+            agent,
+            sessionId,
+            artifact: summaryArtifact
+        });
+        parseSessionSummary(agent, sessionId, summaryPath);
+    }
+    else {
+        appendEvent({
+            type: "session_fallback",
+            agent,
+            sessionId,
+            content: "No session summary was written. Falling back to git snapshots and changed files.",
+            branch: after.branch,
+            changedFiles,
+            newFiles,
+            deletedFiles,
+            diffSummary: after.diffStat
+        });
+    }
+    return { sessionId, sessionDir, exitCode, changedFiles };
+}
+function writeSessionInstructions(agent, sessionId, instructionsPath, summaryPath) {
+    const relativeSummaryPath = path.relative(process.cwd(), summaryPath);
+    const instructions = `# ctxcarry Session Instructions
+
+At the end of this session, write a concise ctxcarry summary to:
+
+${relativeSummaryPath}
+
+Use exactly these Markdown headings:
+
+## Current Task
+## Files Changed
+## Decisions
+## Constraints
+## Failures
+## Commands Run
+## Next Step
+
+Include only durable state the next coding agent needs to continue.
+`;
+    fs.writeFileSync(instructionsPath, instructions);
+}
+function parseSessionSummary(agent, sessionId, summaryPath) {
+    const summary = redactText(fs.readFileSync(summaryPath, "utf8"));
+    const sections = parseMarkdownSections(summary);
+    const task = firstContent(sections["Current Task"]);
+    if (task) {
+        appendEvent({ type: "note", agent, sessionId, noteType: "task", content: task });
+    }
+    for (const file of listContent(sections["Files Changed"])) {
+        appendEvent({ type: "file_changed", agent, sessionId, path: file, change_summary: `Changed during ${sessionId}` });
+    }
+    for (const decision of listContent(sections.Decisions)) {
+        appendEvent({ type: "note", agent, sessionId, noteType: "decision", content: decision });
+    }
+    for (const constraint of listContent(sections.Constraints)) {
+        appendEvent({ type: "note", agent, sessionId, noteType: "constraint", content: constraint });
+    }
+    for (const failure of listContent(sections.Failures)) {
+        appendEvent({ type: "note", agent, sessionId, noteType: "failure", content: failure });
+    }
+    for (const command of listContent(sections["Commands Run"])) {
+        appendEvent({ type: "command_run", agent, sessionId, command, status: "recorded", summary: `Recorded from ${sessionId}` });
+    }
+    const next = firstContent(sections["Next Step"]);
+    if (next) {
+        appendEvent({ type: "note", agent, sessionId, noteType: "next", content: next });
+    }
+    appendEvent({
+        type: "session_summary",
+        agent,
+        sessionId,
+        summaryPath,
+        content: summary
+    });
+}
+function parseMarkdownSections(markdown) {
+    const sections = {};
+    let current = null;
+    for (const line of markdown.split("\n")) {
+        const heading = line.match(/^##\s+(.+?)\s*$/);
+        if (heading) {
+            current = heading[1].trim();
+            sections[current] = "";
+            continue;
+        }
+        if (current) {
+            sections[current] += `${line}\n`;
+        }
+    }
+    return sections;
+}
+function firstContent(section = "") {
+    return listContent(section)[0] ?? section.trim();
+}
+function listContent(section = "") {
+    return section
+        .split("\n")
+        .map((line) => line.trim())
+        .map((line) => line.replace(/^[-*]\s+/, "").replace(/^\d+\.\s+/, ""))
+        .filter(Boolean);
+}
+function spawnInteractive(command, sessionDir, instructionsPath, summaryPath) {
+    const [bin, ...args] = splitCommand(command);
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, args, {
+            cwd: process.cwd(),
+            env: {
+                ...process.env,
+                CTXCARRY_SESSION_DIR: sessionDir,
+                CTXCARRY_SESSION_INSTRUCTIONS: instructionsPath,
+                CTXCARRY_SESSION_SUMMARY: summaryPath
+            },
+            stdio: "inherit",
+            shell: false
+        });
+        child.on("error", reject);
+        child.on("close", (code) => resolve(code ?? 0));
+    });
+}
+function writeSnapshot(sessionDir, name, snapshot) {
+    fs.writeFileSync(path.join(sessionDir, `${name}.json`), JSON.stringify(snapshot, null, 2) + "\n");
+}
+function createSessionId(agent) {
+    const safeAgent = agent.replace(/[^a-z0-9_-]/gi, "-").toLowerCase();
+    return `${new Date().toISOString().replace(/[:.]/g, "-")}-${safeAgent}-${process.pid}`;
+}
+function statusFiles(status, codes) {
+    return unique(status
+        .filter((line) => codes.some((code) => line.trimStart().startsWith(code)))
+        .map((line) => line.slice(3).trim())
+        .filter((file) => !file.startsWith(".ctxcarry/"))
+        .filter(Boolean));
+}
+function splitCommand(command) {
+    const parts = command.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
+    return parts.map((part) => part.replace(/^["']|["']$/g, ""));
+}
+function unique(values) {
+    return [...new Set(values.filter(Boolean))].sort();
+}