agentcache 0.4.2 → 0.5.0-beta.1

package/README.md

@@ -1,172 +1,301 @@
 # AgentCache
 
-**Your codebase learns.** AgentCache compiles what your AI agents discover into a `SKILL.md` that every future session — in any IDE, with any LLM — reads automatically.
+> **Pick a coding session and continue it in another agent.**
+
+**AgentCache 0.5.0-beta.1 is a same-machine public beta.** It keeps a local,
+portable timeline for an explicitly selected coding session, then hands a
+bounded checkpoint to another registered agent through MCP. There is no
+Markdown handoff file to maintain and no silent choice of “latest” session.
+
+The destination agent provider may receive the resume capsule when its agent
+consumes a handoff. In the prescribed prompt-based flow, the handoff ID and
+one-use token may also be sent to the destination provider. Treat the token as
+a temporary bearer secret. “Local-first” describes AgentCache storage and
+coordination; it does not change the network or retention behavior of Claude
+Code, Codex, Cursor, or another hosted agent.
+
+## What it carries
+
+AgentCache carries the useful state around a coding conversation: the goal,
+explicit constraints, completed work, open work, blockers, decisions, rejected
+approaches, next step, portable Git metadata, and a bounded slice of recent
+events. It can keep multiple client legs in one timeline or create an explicit
+fork with an independent child timeline.
+
+It does not transplant a vendor's private conversation object, hidden
+reasoning, system prompt, approval state, or complete tool output. It does not
+intentionally carry credentials: known credential patterns and absolute local
+paths are redacted, but arbitrary secrets may still appear. It does not replace
+a client's own `/resume` command. Native transcript stores are treated as
+read-only sources.
+
+## Five-minute quickstart
+
+Prerequisites: Node.js 22 or newer, two supported clients installed on the same
+machine, and the same canonical repository root open in both clients. Separate
+clones and Git worktrees are isolated in this beta, even when their remotes
+match.
+
+1. Install the pinned beta and run the explicit setup step.
+
+   ```bash
+   npm install -g agentcache@0.5.0-beta.1
+   agentcache setup
+   ```
+
+   Installation has no postinstall configuration hook. Setup is explicit:
+   `agentcache setup` detects installed clients and adds a client-bound MCP
+   entry such as `agentcache serve --adapter codex` when the existing config is
+   unambiguous. Restart or reload clients after setup.
+
+2. Check what AgentCache actually detected and what each adapter can do.
+
+   ```bash
+   agentcache doctor
+   agentcache adapter list --json
+   agentcache adapter doctor claude-code
+   agentcache adapter doctor codex
+   ```
+
+   The global `agentcache doctor` checks exact adapter-bound MCP registrations
+   and, after initialization, the v2 store. On a fresh setup before the first
+   session operation, an absent v2 store is normal: doctor reports the
+   informational message `will initialize on first session operation`. That is
+   not a failure. `adapter doctor` reports the capability evidence for one
+   client.
+
+3. In the source client, ask its AgentCache MCP server to open a portable
+   session for the current workspace, record the goal and relevant progress,
+   and create a checkpoint before you switch. Then, from that repository, list
+   the portable sessions.
+
+   ```bash
+   agentcache session list
+   ```
+
+   Listing also attempts bounded, read-only discovery for adapters whose native
+   history can prove the current workspace. A conversation opened through the
+   AgentCache MCP tools already appears as a portable session.
+
+4. Prepare a handoff with the interactive picker. The destination is always
+   explicit.
+
+   ```bash
+   agentcache session resume --to codex
+   ```
+
+   Search, select a numbered session, inspect it, then choose `continue` or
+   `fork`. Known branches appear in the list. The inspection view shows the
+   exact local workspace path, recovered objective, checkpoint Git state,
+   event count, and an approximate checkpoint-state JSON baseline. The final
+   resume capsule is larger because bounded recent events and its envelope are
+   added later. AgentCache then shows the exact public capsule that the
+   destination will receive. Choose `exclude` to remove numbered events from
+   this handoff's initial capsule and re-preview it, `confirm` to finish, or
+   `cancel` to delete the unconsumed handoff. Nothing is preselected and the
+   picker has no timeout. The one-time token is printed only after confirmation
+   and expires after ten minutes. These local inspection details are not added
+   to the JSON listing contract.
+
+5. Open the same repository in Codex and ask it to call AgentCache's
+   `session_resume` tool with that handoff ID and token. Ask it to restate the
+   goal and next step before continuing. The handoff is accepted only by the
+   chosen adapter in the chosen workspace.
+
+For scripts, specify the session ID and request structured output:
 
 ```bash
-npm install -g agentcache
+agentcache session resume ses_... --to codex --json
 ```
 
-That's it. No config. No accounts. No sync server.
-
----
-
-## The Problem
-
-You tell Claude "don't mock the database in integration tests." It forgets. You tell Cursor the same thing. You tell Codex. You repeat yourself across every IDE, every session, every project.
-
-Your agents are amnesiac. Your knowledge evaporates.
-
-## What AgentCache Does
-
-After a few sessions, AgentCache produces a `SKILL.md` in your repo:
-
-```markdown
-# Project Knowledge
-
-## Rules
-- Never mock the database in integration tests — we got burned when mocks passed but prod migration failed
-- Always use snake_case for database columns
-- Run type-check before committing
-
-## Decisions
-- Using Drizzle ORM over Prisma for raw SQL escape hatches
-- PostgreSQL for all persistent state, Redis for ephemeral cache only
-
-## Context
-- Migrating from REST to GraphQL, both coexist until Q3
-- Auth service rewrite driven by compliance (not tech debt)
-```
-
-This file lives at `<repo>/.agentcache/skills/project-knowledge/SKILL.md`. It's auto-discovered by **38+ tools** that support the Agent Skills spec — no MCP connection required. Commit it. Every teammate gets your team's accumulated knowledge on clone.
-
-**The database is local. The output is git.**
-
-## How It Works
-
-```
-Session 1 (Claude Code)     Session 2 (Cursor)     Session 3 (Codex)
-       │                           │                       │
-       └───────────────────────────┴───────────────────────┘
-                                   │
-                          AgentCache (MCP Server)
-                                   │
-                    ┌───────────────┴───────────────┐
-                    │                               │
-              ~/.agentcache/                  <repo>/.agentcache/
-              agentcache.db                  skills/.../SKILL.md
-              (local SQLite)                 (committed to git)
-```
-
-1. **Session starts** → agent calls `inject_context` → gets compiled rules, lessons, decisions
-2. **During session** → agent calls `compile_submit` as it learns things
-3. **Session ends** → knowledge compiles into the database
-4. **Periodically** → database projects into `SKILL.md` for git distribution
-
-Knowledge compounds. One lesson stated once propagates to every future session across every IDE.
-
-## Install
-
-```bash
-npm install -g agentcache
-```
-
-The install automatically:
-1. Creates `~/.agentcache/agentcache.db`
-2. Detects your IDEs (Claude Code, Cursor, Roo Code, Windsurf, Continue, Codex)
-3. Registers as an MCP server in each — with auto-approve
-4. Sets up Claude Code hooks for transcript recovery
-5. Compiles your existing transcript history in the background
-
-**Zero config. Zero setup. Start a session and it's working.**
-
-## Supported IDEs
-
-| IDE | MCP | Auto-Approve | Transcript Recovery |
-|-----|-----|-------------|-------------------|
-| Claude Code | ✓ | ✓ | Full (hooks + JSONL) |
-| Cursor | ✓ | ✓ | Full (agent transcripts) |
-| Roo Code (VS Code) | ✓ | ✓ | Full (task history) |
-| Codex | ✓ | ✓ | Full (session JSONL) |
-| Continue | ✓ | ✓ | Full (session JSON) |
-| Windsurf | ✓ | ✓ | Incremental only |
-| Goose | — | — | Full (SQLite) |
-
-All IDEs share the same knowledge database. A rule learned in Claude Code is injected in Cursor the next time you open it.
-
-## Security Model
-
-AgentCache creates a feedback loop: agents write observations → observations compile → knowledge injects into future sessions. This is the product's value **and** its attack surface.
-
-**Quarantine gate**: Agent-submitted observations require confirmation across 2+ independent sessions before injection. A single prompt-injected `compile_submit` cannot poison your knowledge.
-
-**Human-only enforcement**: Policy rules (that block tool calls) can only be created via CLI. No MCP tool can create policy.
-
-**Scope gate**: Agent-submitted observations are always project-scoped. Global requires explicit human action.
-
-### Security Modes
-
-```json
-{ "security": "auto" }
-```
-
-| Mode | Behavior |
-|------|----------|
-| `auto` | Quarantine — new items inject after 2+ session confirmations |
-| `review` | Nothing injects until `agentcache review` approves it |
-| `locked` | `compile_submit` disabled. Human-triggered batch only |
-
-## CLI
+Non-interactive and JSON runs never open the picker; they fail if the session
+ID is absent. They return the same bounded public capsule as `session_resume`;
+pass one or more IDs to `--exclude-event <event-id...>` to omit known capsule
+events. Exclusion is
+not deletion or access control: it affects only this initial capsule, and a
+same-workspace destination can still request those events with
+`session_history`. See [the demo script](docs/demo-script.md) for a complete
+Claude Code → Codex → Cursor fork walkthrough.
+
+## Resume and fork semantics
+
+- `continue` adds a new client leg to the same portable session.
+- `fork` creates a child session anchored to an immutable parent checkpoint;
+  later parent and child events remain independent.
+- An active source writer blocks continuation unless the human explicitly
+  confirms takeover with `--confirm-active-source`; for parallel work, fork.
+- A handoff is single-use, expires after ten minutes, and is bound to one
+  destination adapter, workspace, and exact prepared capsule.
+- Interactive cancellation and prompt failures delete the unconsumed draft;
+  superseded drafts are deleted before an exclusion-adjusted capsule is made.
+- A changed session head, wrong destination, wrong workspace, expired token, or
+  reused token is rejected rather than guessed around.
+- Long history is marked partial and can be fetched in bounded pages with
+  `session history` or the MCP `session_history` tool.
+
+## Compatibility
+
+The table below is generated as a documentation contract against the runtime
+adapter registry. `experimental` means the parser or registration is covered by
+fixtures but does not yet have dated live-client evidence. `unsupported` means
+AgentCache will report the limitation instead of pretending the operation
+works. Modes describe how the adapter capability is implemented.
+
+<!-- runtime-capability-matrix:start -->
+| Client | Adapter ID | Registration | History | Native resume | Append | Checkpoint | Fork | Launch |
+|---|---|---|---|---|---|---|---|---|
+| Claude Code | claude-code | experimental / mcp-cooperative | experimental / local-snapshot | unsupported / none | unsupported / none | unsupported / none | unsupported / none | unsupported / none |
+| Cursor | cursor | experimental / mcp-cooperative | experimental / local-snapshot | unsupported / none | unsupported / none | unsupported / none | unsupported / none | unsupported / none |
+| Roo Code | roo-code | experimental / mcp-cooperative | experimental / local-snapshot | unsupported / none | unsupported / none | unsupported / none | unsupported / none | unsupported / none |
+| Windsurf | windsurf | experimental / mcp-cooperative | unsupported / none | unsupported / none | unsupported / none | unsupported / none | unsupported / none | unsupported / none |
+| Continue | continue | experimental / mcp-cooperative | experimental / local-snapshot | unsupported / none | unsupported / none | unsupported / none | unsupported / none | unsupported / none |
+| Codex | codex | experimental / mcp-cooperative | experimental / local-snapshot | unsupported / none | unsupported / none | unsupported / none | unsupported / none | unsupported / none |
+| Goose | goose | experimental / mcp-cooperative | unsupported / none | unsupported / none | unsupported / none | unsupported / none | unsupported / none | unsupported / none |
+<!-- runtime-capability-matrix:end -->
+
+The `native resume`, `append`, `checkpoint`, `fork`, and `launch` columns are
+client-native adapter capabilities. The beta's portable append, checkpoint,
+resume, and fork operations are provided through AgentCache's shared MCP/CLI
+session layer; they do not write those operations into vendor-owned histories.
+Windsurf and Goose historical recovery are unsupported. Goose MCP registration
+uses its documented 1.39 YAML schema but remains experimental.
+
+For evidence, limitations, source formats, and how to read the matrix, see
+[Compatibility](docs/compatibility.md). The live source of truth is:
 
 ```bash
-agentcache doctor                          # Diagnose installation
-agentcache status                          # Knowledge stats
-agentcache review                          # Approve/reject quarantined items
-agentcache promote <id>                    # Approve a single item
-agentcache add-rule "never force push" --enforce   # Create policy (human-only)
-agentcache compile-all                     # Batch-compile all transcripts
-agentcache setup                           # Re-register with IDEs
-```
-
-## compile-all
-
-Processes all uncompiled transcripts from all IDEs using the first available LLM backend:
-
-1. CLI tools: `claude`, `codex`, `gemini`, `copilot`, `aider`, `goose`
-2. Ollama at `localhost:11434`
-3. `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
-
-Runs automatically on install and when pending transcripts exceed 20.
-
-## Data
-
+agentcache adapter list --json
+agentcache adapter doctor <adapter-id> --json
 ```
-~/.agentcache/
-├── agentcache.db          # Knowledge database (SQLite + WAL)
-├── config.json            # Security mode
-└── compile-all.lock       # Prevents concurrent compilation
 
-<repo>/.agentcache/
-└── skills/project-knowledge/SKILL.md   # Git-committed team knowledge
+## Command reference
+
+These are the public beta session-continuity commands. Options are abbreviated
+here; use `agentcache <group> <command> --help` for the complete syntax.
+
+<!-- beta-command-matrix:start -->
+| Command | Purpose |
+|---|---|
+| `session list` | Discover and list sessions for the current workspace. |
+| `session inspect` | Inspect one portable session. |
+| `session resume` | Prepare an explicit one-use destination handoff. |
+| `session append` | Append one human-authorized portable event. |
+| `session checkpoint` | Create one human-authorized checkpoint. |
+| `session fork` | Prepare an explicit fork from a checkpoint. |
+| `session history` | Read a bounded page of portable history. |
+| `handoff list` | List pending handoffs for the current workspace. |
+| `handoff cancel` | Cancel one pending handoff. |
+| `adapter list` | List supported runtime adapter definitions. |
+| `adapter doctor` | Probe one adapter and show capability evidence. |
+| `adapter register` | Register AgentCache with one detected client. |
+| `adapter unregister` | Remove AgentCache-owned registration for one client. |
+<!-- beta-command-matrix:end -->
+
+The exact argument and option contract is checked against the real Commander
+command objects. “Required options” must be present for Commander to invoke the
+handler; angle brackets on an optional option mean that the option takes a
+value, not that the option itself is mandatory.
+
+<!-- cli-help-contract:start -->
+| Command | Arguments | Required options | Optional options |
+|---|---|---|---|
+| `session list` | — | — | `--adapter <id>; --status <status>; --json` |
+| `session inspect` | `<session-id>` | — | `--json` |
+| `session resume` | `[session-id]` | `--to <adapter>` | `--checkpoint <id>; --fork; --confirm-active-source; --exclude-event <event-id...>; --json` |
+| `session append` | `<session-id>` | `--kind <kind>` | `--text <text>; --stdin; --json` |
+| `session checkpoint` | `<session-id>` | — | `--summary <text>; --summary-file <path>; --state-file <path>; --json` |
+| `session fork` | `<session-id>` | `--from <checkpoint-id&#124;latest>; --to <adapter>` | `--title <title>; --exclude-event <event-id...>; --json` |
+| `session history` | `<session-id>` | — | `--before <cursor>; --limit <number>; --json` |
+| `handoff list` | — | — | `--json` |
+| `handoff cancel` | `<handoff-id>` | — | `--json` |
+| `adapter list` | — | — | `--json` |
+| `adapter doctor` | `<adapter-id>` | — | `--json` |
+| `adapter register` | `<adapter-id>` | — | — |
+| `adapter unregister` | `<adapter-id>` | — | — |
+<!-- cli-help-contract:end -->
+
+`session append` requires exactly one of `--text` or `--stdin`. `session
+checkpoint` accepts at most one of `--summary`, `--summary-file`, or
+`--state-file`. A non-interactive or `--json` resume requires an explicit
+session ID.
+
+## Data flow and safety boundary
+
+```text
+read-only native history (when verified)
+        │ bounded read + normalization + redaction
+        ▼
+~/.agentcache/agentcache-v2.db
+        │ explicit checkpoint + one-use handoff
+        ▼
+destination MCP session
+        │ hosted-client provider boundary
+        ▼
+destination model
 ```
 
-No network calls. No telemetry. No accounts. Everything stays on your machine (except what you choose to commit).
-
-## Principles
-
-- **Zero config** — `npm install -g` is the only step
-- **Universal** — MCP protocol, any IDE, any LLM
-- **Git-native output** — SKILL.md is the distribution mechanism
-- **Secure by default** — quarantine gate, scope restrictions, human-only policy
-- **Anti-bloat** — 30-day decay, budget caps, confidence promotion
-
-## Contributing
+AgentCache stores v2 session data locally with user-only filesystem
+permissions. It rejects symbolic, special, or multiply linked database and
+SQLite sidecar paths, uses bounded transcript reads, rejects transcript
+symlinks, redacts known credential shapes and absolute local paths from
+portable text, and labels resume data `untrusted_prior_session_context`.
+Redaction is defense in depth, not a proof that arbitrary secrets cannot
+appear; inspect sensitive sessions before handing them to another provider.
+
+Setup does not add blanket AgentCache tool approvals. Registration updates are
+atomic, back up an existing configuration before a material change, and leave
+malformed or ambiguous configurations untouched. AgentCache does not mutate Git
+or write generated context into a repository in the default beta path.
+
+Read the complete [privacy and trust boundary](docs/privacy.md) before using the
+beta with sensitive repositories.
+
+## Beta limits
+
+- Same machine only. Cloud sync, accounts, teams, and cross-device continuation
+  are deferred.
+- There is no native picker UI; the terminal picker is the control plane.
+- Native client history formats can change. All current adapters are marked
+  experimental or unsupported until dated live-client verification exists.
+- Windsurf and Goose can participate prospectively through MCP registration,
+  but their historical recovery is unsupported.
+- AgentCache cannot carry hidden reasoning, private provider state, or tool
+  approvals between clients.
+- A Markdown fallback is intentionally not generated when a destination is
+  unavailable; the pending handoff remains until it is consumed, cancelled, or
+  expires.
+
+## Legacy 0.4 data
+
+Version 0.5 creates `~/.agentcache/agentcache-v2.db` beside the legacy
+`~/.agentcache/agentcache.db`; it does not translate or mutate compiled v1
+knowledge. Legacy v1 CLI commands are not registered in the beta: `compile-session`,
+`discover`, `enforce`, `review`, `promote`, `add-rule`, `compile-all`, and
+`status` are unavailable. Setup, installation, startup, session discovery, and
+idle operation cannot invoke legacy compilation. Automatic `SKILL.md`
+generation is not part of the beta path.
+
+This preserves the original “your codebase learns” experiment without making
+its legacy compiler the trust boundary for cross-agent continuation.
+
+## Operations and feedback
+
+- [Troubleshooting, uninstall, and rollback](docs/troubleshooting.md)
+- [Privacy and data flow](docs/privacy.md)
+- [Compatibility details](docs/compatibility.md)
+- [60–90 second demo](docs/demo-script.md)
+- [Launch copy](docs/launch-copy.md)
+- [Open a structured beta-feedback issue](https://github.com/raghav-a21ai/agentcache/issues/new?template=beta-feedback.yml)
+
+## Development
 
 ```bash
 git clone https://github.com/raghav-a21ai/agentcache
 cd agentcache
 npm install
+npm run typecheck
 npm run build
-npm test   # 205 tests
+npm test
 ```
 
 ## License