agentcache 0.4.1 → 0.5.0-beta.1

package/README.md

@@ -1,250 +1,299 @@
 # AgentCache
 
-Your AI coding agents forget everything between sessions. AgentCache fixes that — it learns what you know, remembers it across sessions, and injects it into every future agent automatically, across every IDE.
-
-> "Don't mock the database in integration tests — we got burned when mocked tests passed but prod migration failed"
-
-That lesson, learned once, becomes a permanent rule. Every future session with every IDE gets it. You never say it again.
-
-## What it does
-
-AgentCache observes your coding sessions and compiles reusable knowledge — rules, lessons, architectural decisions, project context — into a local database. Every future session gets that knowledge injected at the start, regardless of IDE or LLM.
-
-- **Learns** from what your agents discover during sessions
-- **Injects** relevant knowledge at the start of every new session
-- **Works everywhere** — any IDE, any LLM, simultaneously
-- **Stays local** — SQLite on your machine, nothing leaves your disk
-
-## Install
+> **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
-```
-
-Done. Start a session in any IDE — AgentCache is already running.
-
-No init. No setup. No config. The install:
-
-1. Creates `~/.agentcache/agentcache.db`
-2. Detects installed IDEs (Claude Code, Cursor, Roo Code, Windsurf, Continue, Codex)
-3. Registers itself as an MCP server in each
-4. Sets up Claude Code hooks for automatic transcript recovery
-5. Spawns `compile-all` in background to process your existing transcript history
-
-## Team knowledge — without a sync server
-
-Compiled project knowledge is written to `<repo>/.agentcache/skills/project-knowledge/SKILL.md`. Commit it. Every teammate gets your team's accumulated decisions and context on clone, automatically picked up by any Agent Skills-compatible tool.
-
-```markdown
-## Decisions
-- Using Drizzle ORM over Prisma for raw SQL escape hatches
-- PostgreSQL for all persistent state, Redis for ephemeral cache only
-
-## Current Context
-- Migrating from REST to GraphQL, both coexist until Q3
-```
-
-No sync server. No accounts. Just git.
-
-## How it works
-
-```
-┌────────────────────────────────────────────────────────────────────────┐
-│                           Your Machine                                 │
-│                                                                        │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
-│  │  Claude  │  │  Cursor  │  │   Roo    │  │  Codex   │  ...         │
-│  │   Code   │  │          │  │   Code   │  │          │              │
-│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘              │
-│       └─────────────┴─────────────┴─────────────┘                     │
-│                              │ MCP Protocol (stdio)                    │
-│                 ┌────────────┴────────────┐                            │
-│                 │  AgentCache MCP Server  │                            │
-│                 └────────────┬────────────┘                            │
-│                              │                                         │
-│                    ┌─────────┴──────────┐                              │
-│                    │  ~/.agentcache/    │                              │
-│                    │  agentcache.db     │                              │
-│                    │  (SQLite + WAL)    │                              │
-│                    └────────────────────┘                              │
-└────────────────────────────────────────────────────────────────────────┘
-```
-
-### The cycle
-
-1. **Session starts** — agent calls `inject_context` → receives compiled rules, lessons, decisions
-2. **During session** — agent calls `compile_submit` incrementally as it learns things
-3. **Session ends** — observations are already saved. If the session terminates unexpectedly, transcript recovery handles it next time.
-
-### Knowledge types
-
-| Type | Scope | Example |
-|------|-------|---------|
-| Rule | Global | "Always use snake_case for database columns" |
-| Lesson | Global | "Don't mock the database in integration tests — mocked tests passed but prod migration failed" |
-| Decision | Project | "Using Drizzle ORM over Prisma because we need raw SQL escape hatches" |
-| Context | Project | "Currently migrating from REST to GraphQL, both coexist" |
-
-Rules and lessons are global — they apply to all your projects. Decisions and context are project-scoped.
-
-## Security model
-
-AgentCache creates a persistent feedback loop: agents write observations → observations compile into knowledge → knowledge injects into future sessions. This is the product's core value **and** its main attack surface. Both are the same thing.
-
-### What the security model guarantees
-
-- **Quarantine by default** — AUTO observations (agent-submitted) are never injected until confirmed across 2+ independent sessions. A single prompt-injected `compile_submit` call cannot poison your knowledge base — it lands in quarantine and requires independent reinforcement before it's ever served.
-- **Enforced rules are human-only** — The enforce mechanism (which blocks agent tool calls) can only be set via CLI (`agentcache add-rule --enforce`). No MCP tool can create policy an agent is subject to.
-- **Scope gate** — Agent-submitted observations are always project-scoped. Promotion to global scope requires explicit human action (USER authority). An agent cannot write a global rule.
-- **Quarantine ≠ absent** — Quarantined items are captured and visible in `agentcache review`. They just don't inject. The review command is how you clear or promote them.
-
-### What the security model does not guarantee
-
-- `compile-all` processes raw transcripts that may contain injected content. Extraction prompt hardening raises the bar, but a sufficiently crafted transcript can still produce a quarantined (non-injecting) entry. Review your pending queue periodically.
-- `locked` mode disables `compile_submit` entirely and requires human-triggered batch compilation. It reduces the attack surface significantly but `compile-all` against a poisoned transcript is still a vector.
-
-### Security modes
-
-Configure in `~/.agentcache/config.json`:
-
-```json
-{ "security": "auto" }
+agentcache session resume ses_... --to codex --json
 ```
 
-| Mode | Behavior | For |
-|------|----------|-----|
-| `auto` (default) | Quarantine — AUTO items inject after 2+ session confirmations | Solo devs, indie shops |
-| `review` | All new items land in quarantine. Nothing injects until `agentcache review` approves it | BFSI, healthcare, regulated environments |
-| `locked` | `compile_submit` disabled. Compile-all only, human-triggered batch review | Maximum control |
-
-## CLI commands
+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 status          # Knowledge stats for current project
-agentcache doctor          # Diagnose installation problems
-agentcache review          # List quarantined items, approve or reject
-agentcache promote <id>    # Promote a single item past quarantine
-agentcache add-rule "never commit secrets" --enforce  # Create enforced policy (human only)
-agentcache add-rule "use tabs" --global              # Global rule across all projects
-agentcache compile-all     # Batch-compile all unprocessed transcripts
-agentcache setup           # Re-register with IDEs (only if postinstall failed)
+agentcache adapter list --json
+agentcache adapter doctor <adapter-id> --json
 ```
 
-## compile-all — batch compilation
-
-Processes all pending transcripts without depending on active MCP sessions.
-
-**LLM backend (first available wins):**
-
-1. CLI tools with stored auth: `claude`, `codex`, `gemini`, `copilot`, `aider`, `goose`
-2. Ollama at `localhost:11434`
-3. `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
-
-**Triggers automatically:**
-
-- After `npm install -g agentcache` (clears initial backlog)
-- When pending transcripts exceed 20 (background janitor)
-- Lockfile prevents concurrent runs
-
-## MCP tools
-
-| Tool | Purpose |
-|------|---------|
-| `inject_context` | Load compiled knowledge at session start |
-| `compile_submit` | Submit observations incrementally during session |
-| `compile_cluster` | Resolve clustering when observations overlap existing knowledge |
-| `compile_extract` | Process queued transcripts from previous sessions |
-| `enforce` | Check tool calls against enforced policy rules |
-| `save_observation` | Save a permanent observation (USER authority, never auto-deprecated) |
-| `get_knowledge` | Query the knowledge database |
-| `deprecate_knowledge` | Mark knowledge as deprecated |
-
-## How knowledge compiles
-
+## 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
 ```
-Observations (raw)
-    │
-    ▼
-Extract → Normalize → Canonicalize → Cluster → Detect Contradictions → Compile
-                                                                          │
-                              ┌───────────────────────────────────────────┘
-                              │
-                         PENDING store
-                              │
-                    ┌─────────┴──────────┐
-                    │                    │
-              AUTO items           USER items
-         (quarantine gate)      (inject immediately)
-         2+ sessions before
-            injection
-```
-
-**Two compilation paths:**
-
-- **In-session** — agent processes extraction via MCP tools in your IDE
-- **Batch** — `compile-all` runs independently, processes full backlog
-
-**Two output formats:**
-
-- **MCP injection** — structured context via `inject_context`
-- **SKILL.md** — Agent Skills spec files auto-discovered by 38+ tools without MCP
-
-## Design principles
-
-**Zero config** — `npm install -g agentcache` is the only step. No dotfiles, no init, no config to maintain.
-
-**Universal** — MCP is the only interface. Any IDE, any LLM. No IDE-specific code paths.
-
-**Developer-scoped** — One database per developer, not per project. Global knowledge (rules, lessons) benefits all your projects. Project knowledge stays scoped.
-
-**Resilient to abrupt exits** — Incremental submission + transcript recovery + pipe-independent compilation means knowledge survives crashes, ctrl-c, and MCP disconnects.
-
-**Anti-bloat** — Confidence promotion, 30-day decay on unused items, budget caps (20 rules / 10 lessons / 10 decisions / 5 context per session), priority ranking.
-
-## Supported IDEs
-
-| IDE | MCP | Auto-Approve | Transcript Recovery | Hooks |
-|-----|-----|-------------|-------------------|-------|
-| Claude Code | Yes | Yes | Full (JSONL) | Stop, SessionStart, PreToolUse |
-| Cursor | Yes | Yes | Incremental only | — |
-| Roo Code | Yes | Yes | Full (JSON via compile-all) | — |
-| Windsurf | Yes | Yes | Incremental only | — |
-| Continue | Yes | Yes | Full (JSON) | — |
-| Codex | Yes | Yes | Full (JSONL via compile-all) | — |
-| Goose | — | — | Full (SQLite via compile-all) | — |
-| Aider | Coming soon | | | |
-| GitHub Copilot | Coming soon | | | |
-| Zed AI | Coming soon | | | |
-
-## Data storage
-
-```
-~/.agentcache/
-├── agentcache.db                          # Knowledge, observations, sessions, pending queue
-├── config.json                            # Security mode and settings
-├── compile-all.lock                       # Prevents concurrent compilation
-└── skills/developer-knowledge/SKILL.md    # Global skill (auto-generated)
-```
-
-No data leaves your machine. No network calls. No telemetry. No accounts.
-
-### Project identity
-
-Projects are identified by a hash of their full filesystem path. `/work/api` and `/personal/api` are different projects. Knowledge never leaks between same-named projects in different locations.
-
-## Roadmap
-
-- **Native plugins** — Marketplace listings and deeper UI integrations for all supported IDEs
-- **Team knowledge sharing** — Share compiled knowledge across your team
-- **Cloud sync** — Same developer, different machines, same knowledge
-- **Analytics dashboard** — Compilation stats, knowledge growth, most-referenced rules
 
-## 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
 ```