agentel 0.2.0

package/agentlog-spec.md

@@ -0,0 +1,551 @@
+# agentlog — spec v0.2
+
+A weekend-buildable archive and recall layer for agent coding sessions across Codex, ChatGPT exports, Claude, Gemini, Antigravity, Devin, and Cursor. Local-first, optionally cloud-backed via any S3-compatible storage. Web chats from ChatGPT and Claude.ai are importable via their official export flows. Windsurf is disabled until Cascade exposes a readable local transcript path.
+
+## What it does
+
+Agentlog optimizes for four product constraints:
+
+1. **Preserve the source history as-is.** Import copies raw source files into the archive before normalizing them, so agentlog can re-parse sessions as provider formats change.
+2. **Create a durable recall substrate.** Readable markdown plus canonical event JSONL is the source of truth for `/recall` skills, MCP tools, coding agents, and standardization across providers.
+3. **Show full histories clearly.** The CLI and local web viewer must make complete conversation histories easy to browse, search, export, and inspect without hiding tool calls or context.
+4. **Sync across machines.** Local storage remains canonical, but every archive object should be syncable to S3-compatible storage or another cloud target for backup, restore, and multi-device recall.
+
+Three layers, separable, in priority order:
+
+1. **Archive** — every agent session is captured as readable markdown plus raw transcripts, redacted at ingest, written to S3-compatible storage keyed by canonical repo identity.
+2. **Recall** — an MCP server exposing one tool, `search_past_sessions(query, repo, limit)`, that searches canonical event JSONL first and falls back to markdown/transcript retrieval. Available to any MCP-capable agent and wrapped by installable agent commands/skills.
+3. **Notify** — optional `/buzz`-style Slack skill that posts session summaries on completion. Cut from v0; ships separately as `agentlog-slack`.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│  Agents (Claude Code, Codex, Devin, Cursor)     │
+└──────────────┬──────────────────────────────────┘
+               │
+        ┌──────┴───────┐
+        │              │
+   OTel push       File tail / poll
+   (Claude Code)   (Codex JSONL,
+   (Cowork)        Cursor SQLite)
+        │              │
+        └──────┬───────┘
+               ▼
+   ┌───────────────────────┐         ┌──────────────────┐
+   │  agentlog supervisor  │◄────────│  Web chat import │
+   │  ├─ collector         │         │  (Claude.ai,     │
+   │  ├─ openobserve       │         │   ChatGPT export │
+   │  ├─ codex-watcher     │         │   files)         │
+   │  ├─ cursor-poller     │         └──────────────────┘
+   │  ├─ indexer           │
+   │  └─ importer          │
+   └──────────┬────────────┘
+              ▼
+   ┌───────────────────────┐
+   │  S3-compatible bucket │
+   │  (R2 / S3 / B2 /      │
+   │   MinIO / etc)        │
+   └──────────┬────────────┘
+              ▼
+   ┌───────────────────────┐
+   │  agentlog-recall MCP  │      ┌─────────────────────┐
+   │  (stdio, on-demand)   │      │  agentlog history   │
+   │  search_past_sessions │      │  (cchv-based)       │
+   └───────────────────────┘      └─────────────────────┘
+```
+
+## Process model
+
+**One supervisor, several workers.** The supervisor is the only process the user thinks about. It manages child processes, handles restarts with backoff, exposes a control socket at `~/.agentlog/control.sock`, and unifies logging.
+
+**Always-on workers (run inside the supervisor):**
+
+- OTel collector — receives Claude Code's OTLP pushes, ~40MB RAM
+- OpenObserve — local-mode storage and query, ~100MB RAM (skipped in remote/team mode)
+- Codex watcher — `fsnotify` on `~/.codex/sessions/`, ~10MB RAM, idle when no Codex activity
+- Devin/Cursor pollers — SQLite/transcript scans for configured local sources
+- Indexer — runs every 10 minutes if there are unindexed sessions; pauses on battery
+- Importer — runs at low priority during backfill operations; idle otherwise
+
+**On-demand workers (launched by their caller):**
+
+- `agentlog-recall` MCP server — spawned by the agent client over stdio when a session starts; killed when the session ends. No always-on cost.
+
+**Total always-on footprint, solo install:** ~150MB RAM, near-zero idle CPU. Comparable to a menu-bar chat app.
+
+**Team mode inverts this:** developer machines run only the collector and watchers (~50MB total) and forward OTLP to a team server that runs OpenObserve, the indexer, and the recall HTTP endpoint.
+
+## Auto-start at login
+
+`init` offers to install a platform-native login agent. Default: yes, with explicit opt-out.
+
+**Prompt during init:**
+
+```
+agentlog can start automatically when you log in.
+
+This runs a small background service (~150MB RAM) that captures
+your agent conversations as they happen. You can stop it anytime
+with `agentlog stop` or remove auto-start with `agentlog uninstall`.
+
+Start agentlog automatically at login? [Y/n]
+```
+
+**Per-platform implementation:**
+
+- **macOS:** `~/Library/LaunchAgents/com.agentlog.supervisor.plist`. `RunAtLoad: true`, `KeepAlive: { SuccessfulExit: false }` (restart on crash, not on clean shutdown). Logs to `~/Library/Logs/agentlog/`. Loaded with `launchctl load -w`.
+- **Linux:** systemd user unit at `~/.config/systemd/user/agentlog.service`. `Type=simple`, `Restart=on-failure`, `RestartSec=5`. Enabled with `systemctl --user enable --now`. Init detects whether `loginctl enable-linger` is needed and prompts separately: "Keep agentlog running when you're logged out? [y/N]" — default no.
+- **Windows:** Scheduled Task triggered at logon (`schtasks /create /tn "agentlog" /tr ... /sc onlogon`). Service-based install is a v1 enhancement.
+
+**Critical detail:** the launch agent runs `agentlog start --foreground`, not `agentlog start`. Foreground mode keeps the OS supervisor (launchd/systemd/Task Scheduler) as the parent — detaching breaks process tracking and crash restart.
+
+**Lifecycle commands:**
+
+```
+agentlog autostart enable     # writes the launch agent/unit/task
+agentlog autostart disable    # removes auto-start, keeps agentlog installed
+agentlog autostart status     # shows current state
+agentlog uninstall [--keep-data]
+```
+
+`uninstall` is exhaustively tested: removes the launch agent, the config, the binaries, optionally the data (with confirmation). For a tool handling sensitive data, "remove all traces" must actually work.
+
+## Resource awareness
+
+The supervisor respects laptop realities:
+
+- **Power state.** On battery, indexer interval drops from 10 to 30 minutes; compaction skipped; speculative pre-fetching disabled.
+- **Network state.** If storage backend is remote and we're offline, writes spool to `~/.agentlog/spool/` and flush on reconnect. The OTLP collector already does this for spans; the same pattern extends to S3 writes.
+- **Sleep/wake.** On wake, supervisor verifies child health and restarts any that died during sleep.
+- **Cursor presence.** Cursor poller checks `pgrep -x Cursor` before each poll cycle; sleeps entirely when Cursor is not running.
+
+These are v0 features, not v1, because they're the difference between a tool people keep installed and a tool people uninstall after a week.
+
+## Storage layer
+
+**Backend: anything S3-compatible.** Backend choice is a config matter, not a code matter. Supported in `init`:
+
+- **Local** (default first-run) — `~/.agentlog/data/`, no cloud account
+- **R2** (recommended for personal/small team) — Cloudflare, no egress fees, free 10GB tier
+- **S3** (recommended for AWS-native teams)
+- **Custom endpoint** — covers B2, MinIO, Wasabi, Tigris, Hetzner, etc.
+
+**Bucket layout:**
+
+```
+s3://<bucket>/agentlog/
+  devices/
+    <device-name>/
+      sessions/
+        repo=<canonical-repo-key>/
+          provider=<claude_code|codex|cursor|devin>/
+          year=2026/month=04/day=26/
+            session=<session_id>.conversation.md
+            session=<session_id>.transcript.jsonl
+            session=<session_id>.metadata.json
+            session=<session_id>.events.jsonl
+        scope=<claude-web|chatgpt>/
+          year=2026/month=04/day=26/
+            session=<session_id>.conversation.md
+            session=<session_id>.transcript.jsonl
+            session=<session_id>.metadata.json
+            session=<session_id>.events.jsonl
+      indexes/
+        bm25/...       # local keyword/BM25-style index over events/transcripts
+  snapshots/
+    20260504T173000Z/
+      <device-name>/
+        sessions/...
+```
+
+Markdown conversations are the primary human-readable representation because
+agents and humans can inspect them with ordinary filesystem tools. Raw
+transcripts are stored alongside as immutable JSONL for provenance and
+re-indexing. `events.jsonl` is the canonical machine-readable recall substrate:
+one provider-independent JSONL event stream with `session.started`,
+`prompt.submitted`, `response.generated`, `tool.called`, and `tool.completed`.
+Structured analytics artifacts such as Parquet/OTel spans are optional siblings,
+not the default recall substrate.
+
+Every importer has a centralized semantic parser version in
+`src/parser-versions.js`. Parser versions are included in archive metadata and
+import fingerprints. The first npm release uses `1.0.0` as the baseline for
+every source type. After release, when parser output changes for the same raw
+input, the source-type version must be bumped in the same change so stale
+archives can be replaced.
+
+**Migration:** `agentlog migrate --to <backend>` records the remote target; `agentlog sync` uploads the same markdown-primary object layout to any S3-compatible target under `agentlog/devices/<device-name>/...`. Local→R2 is a one-shot upload and then an incremental supervisor upload. Sync does not delete remote objects. Receive-only and two-way sync should read other device namespaces and merge normalized archive metadata without interpreting absence on one device as a delete. `agentlog snapshot` writes redundant point-in-time copies under `agentlog/snapshots/<timestamp>/<device-name>/...`.
+
+## Repo keying
+
+Every span and record gets `agentlog.repo.canonical`, derived in this order:
+
+1. `git config --get remote.origin.url` from the session's `cwd`, normalized: lowercase host, strip protocol, strip `.git`, strip trailing slash. `git@github.com:User/Repo.git` → `github.com/user/repo`.
+2. First-commit SHA fallback: `git rev-list --max-parents=0 HEAD` → `firstcommit:<sha>`.
+3. Non-git fallback: content hash of cwd path normalized to home-relative → `path:<sha256>`.
+
+Repo-level override at `.agentlog.yaml`:
+
+```yaml
+canonical_repo: github.com/myorg/private-name
+aliases:
+  - github.com/myorg/old-name
+```
+
+Web chat imports use `agentlog.scope.canonical` instead (e.g. `claude-web`, `chatgpt`) — see Web chat import section.
+
+## Redaction (at ingest, not at query)
+
+Three layers in the collector before anything hits storage:
+
+1. **Built-in patterns** (always on):
+   - AWS keys, OpenAI/Anthropic keys, GitHub tokens, Slack tokens
+   - JWT-shaped strings, private key blocks
+   - High-entropy strings >32 chars in `KEY=value` shapes
+
+2. **Env-var value scrubbing.** If `.env` files are read in a session, configured variable values are scrubbed wherever they appear in transcripts.
+
+3. **User-defined patterns** in `~/.agentlog/redaction.yaml`:
+
+```yaml
+patterns:
+  - name: internal_api
+    regex: 'https://[a-z]+\.internal\.acme\.com/[^\s]+'
+env_vars: [API_KEY, DATABASE_URL, STRIPE_SECRET]
+allowlist_repos:
+  - github.com/acme/public-docs
+```
+
+Each session gets a `redaction_summary` span: counts by category, no content. Users can audit "did this leak anything" without seeing what leaked.
+
+`agentlog reveal <session-id>` re-renders un-redacted from local cache. Local-only — never works on remote/team archives.
+
+**Honesty about limits:** pattern-based redaction catches credentials. It does not catch personal/sensitive content (medical, legal, financial conversations). This matters especially for web chat imports, which is why those default to local-only storage.
+
+## Per-provider capture
+
+### Claude Code & Claude Cowork
+
+Native OTel. `init` merges into `~/.claude/settings.json`:
+
+```json
+{
+  "env": {
+    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
+    "OTEL_METRICS_EXPORTER": "otlp",
+    "OTEL_LOGS_EXPORTER": "otlp",
+    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/json",
+    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318",
+    "OTEL_LOG_USER_PROMPTS": "1",
+    "OTEL_RESOURCE_ATTRIBUTES": "service.name=claude-code,agentlog.user=<user>"
+  }
+}
+```
+
+### Codex CLI
+
+`fsnotify` watcher on `~/.codex/sessions/YYYY/MM/DD/`. Decompresses `.jsonl.zst`, normalizes to OTel `gen_ai.*` spans, posts to local collector. State (file offsets) in `~/.agentlog/state/codex-cursor.db` SQLite. ~200 lines of Go. Deleted when OpenAI ships native OTel.
+
+### Cursor
+
+SQLite/transcript poller, 30-second interval, only active when `Cursor` process detected. Reads older `~/Library/Application Support/Cursor/User/workspaceStorage/*/state.vscdb` stores and newer `~/.cursor/projects/<project>/agent-transcripts/` JSON/JSONL transcripts on macOS/Linux. macOS Full Disk Access prompt documented with screenshots.
+
+### Devin
+
+SQLite importer for Devin for Terminal. Reads
+`~/.local/share/devin/cli/sessions.db`, reconstructs the visible message branch
+from `sessions.main_chain_id` plus `message_nodes.parent_node_id`, skips Devin's
+injected context messages, and archives user, assistant, and tool messages under
+provider `devin`. `AGENTLOG_DEVIN_SESSIONS_DB` can point at an alternate
+database.
+
+### Web chat import (Claude.ai, ChatGPT)
+
+Web chats don't have a real-time hook — Anthropic and OpenAI provide periodic export files only. agentlog imports these as one-shot operations per export.
+
+**Flow:**
+
+1. User exports from Claude.ai (Settings → Privacy → Export) or ChatGPT (Settings → Data Controls → Export)
+2. Email arrives with download link
+3. User runs: `agentlog import claude-web --file <downloaded file>` or `agentlog import chatgpt --file <downloaded file>`
+
+**Storage scope:** local-only by default, **even if the agentlog instance is configured for a team backend.** Web chats often contain personal content; opt-in required to share with team. Override with `--scope team`.
+
+**Repo keying:** web chats are stored under `scope=claude-web` or `scope=chatgpt` rather than a repo key. Heuristic repo inference (matching code blocks and error messages against known repos) deferred to v1.
+
+**Recall behavior:** excluded from agent-initiated `search_past_sessions` calls by default. Included in human-initiated `agentlog history` searches. Override via `--include-web-chats` flag on recall queries.
+
+**Frequency:** designed for periodic re-import, not continuous capture. Realistic cadence is "monthly or when the user remembers." Detection of new exports in `~/Downloads/` and prompting is a v1 enhancement.
+
+**Confirmation prompt for team-configured installs:**
+
+```
+$ agentlog import claude-web --file ...
+Storage backend: team (s3://acme-agentlog/)
+Web chats often contain personal content. By default they'll be
+stored only in your local archive, not the team archive.
+
+  1) Local only (recommended)
+  2) Team archive (your conversations will be visible to teammates)
+  3) Cancel
+```
+
+## Importing existing CLI history
+
+`init` scans for existing CLI conversations and offers to import them. The default scope is "last 30 days" — recent enough to be useful for recall, narrow enough to avoid surprises in archives users may have forgotten the contents of.
+
+**Discovery during init:**
+
+```
+Scanning for existing conversations...
+✓ Codex CLI: 89 sessions across 12 projects (oldest: 2025-09-15)
+✓ Codex Desktop: 14 sessions across 3 projects (oldest: 2026-02-01)
+✓ Claude Code CLI: 247 sessions across 18 projects (oldest: 2025-11-03)
+✓ Claude Code Desktop: 4 sessions (oldest: 2026-02-04)
+✓ Claude Workspace: 7 sessions (oldest: 2026-02-04)
+✓ Gemini CLI: 2 sessions (oldest: 2026-03-01)
+✓ Antigravity: 2 sessions (oldest: 2025-11-19)
+✓ Devin CLI: 3 sessions (oldest: 2026-04-28)
+✓ Cursor: 31 sessions across 4 workspaces (oldest: 2026-01-02)
+
+Import existing history?
+  1) Last 30 days (default)
+  2) Everything
+  3) Choose specific repos
+  4) Skip for now
+```
+
+Import runs as a background worker at lower priority than live ingestion. Progress visible via `agentlog import status`. Idempotent on re-run (tracks imported session IDs in state DB). Sessions whose `cwd` no longer exists fall back to path-hash repo keying.
+
+**Standalone command:**
+
+```
+agentlog import [--source codex-cli|codex-desktop|claude|claude-code-desktop|claude-workspace|gemini-cli|antigravity|devin-cli|cursor|all]
+                [--since 30d|all]
+                [--repos <list>]
+                [--dry-run]
+```
+
+`--dry-run` shows what would be imported without doing it.
+
+**Web chat import is a separate command** — it requires a file argument and has different default storage scope. Not part of the init flow because exports take time to generate.
+
+## Collector
+
+A single Go binary wrapping the upstream OTel collector with three custom processors:
+
+1. `repokeyprocessor` — derives canonical repo key from `cwd`, or scope key for web chats
+2. `redactionprocessor` — runs the three redaction layers
+3. `agentnormalizer` — for file-tail providers and import sources, converts ingested events into OTel spans matching `gen_ai.*` semantic conventions
+
+Exporters: OTLP→OpenObserve for spans/metrics/logs; direct `s3exporter` for raw transcripts. Both share S3 credentials.
+
+## Recall layer
+
+Separate binary, `agentlog-recall`. Spawned by agent clients over stdio (preferred) or run as HTTP server for team mode.
+
+**One MCP tool:**
+
+```
+search_past_sessions(query: string, repo?: string, limit?: int = 10,
+                     include_web_chats?: bool = false)
+  → list of message excerpts with session links
+```
+
+**Recall pipeline:**
+
+- Builds a local keyword/BM25-style index over `events.jsonl` when present
+- Indexes prompt, response, tool-call, and tool-result event text independently
+- Aggregates event hits back to sessions for CLI/MCP compatibility
+- Returns optional `event_id`, `event_kind`, `message_index`, and matched text
+- Falls back to transcript/markdown search for legacy archives without events
+
+**Retrieval:** event-first over canonical JSONL. `repo` parameter is a hard filter.
+Without it, results are weighted toward the calling agent's current `cwd` repo.
+Web chats are excluded unless `include_web_chats=true`.
+
+**No memory promotion in v0.** Raw evidence with good retrieval beats lossy summarization. Add summarization in v1 only if v0 retrieval proves insufficient.
+
+**Adding to agents:**
+
+```
+agentlog recall add-to claude    # writes ~/.claude/mcp.json, /commands/recall.md, and /skills/agentlog-recall/SKILL.md
+agentlog recall add-to cursor    # writes ~/.cursor/mcp.json
+agentlog recall add-to codex     # writes ~/.codex/config.toml
+```
+
+Generated recall commands and skills should let the agent choose the first
+`agentlog history` query from the user's request. They should prefer concise,
+distinctive search terms over blindly passing the full `/recall` argument string
+through to the CLI. Skill-style files should include a concise command table,
+workflow, query-selection guidance, archive/filter hints, important rules, and
+troubleshooting. Archive hints should note that sessions live under
+`~/.agentlog/data/agentlog/sessions/repo=<repo-or-path-key>/provider=<provider>/...`,
+git repos use canonical keys like `github.com/org/repo`, non-git directories may
+use stable `path:<hash>` keys, and `agentlog history --repo "<repo-or-path>"`
+matches canonical repo keys, local `cwd`, display labels, web scopes, and path
+fragments.
+
+## History viewer
+
+v0 ships a dependency-free local viewer behind `agentlog history --web`. It lists sessions in a repo tree sorted by last updated time, pages large folders with a load-more control, searches the same event-first recall index, filters by repo/provider/date, and opens full conversations through the CLI API. The static viewer follows shadcn/ui-style tokens and compact button/input/select/sidebar patterns without requiring a frontend build step. Stable `path:<hash>` keys remain valid archive identifiers for folders without git identity, but the viewer displays the local folder path. The transcript pane defaults to readable chat bubbles for user, assistant, system, and tool messages, with a markdown toggle for the canonical archive file. Tool rendering reads canonical events or normalized metadata first, uses category/icon/target fields for consistent Bash/edit/read/search/web/task/skill/MCP cards, and uses raw text patterns only for legacy archives.
+
+**Commands:**
+
+```
+agentlog history                          # native app pointed at archive
+agentlog history --web                    # web UI on localhost:7824
+agentlog history "query" --provider codex-cli
+agentlog history --repo github.com/org/repo
+agentlog history --since 7d
+agentlog history --include-web-chats
+agentlog show <session-id>
+```
+
+The viewer's search hits the same retrieval endpoint as the recall MCP server — humans and agents see the same world (with the human-vs-agent default scope difference for web chats).
+
+**For headless/server contexts** (SSH'd into a dev box), `--web` mode serves the UI on a local port with a bearer-token-in-URL auth pattern.
+
+**Team mode** serves cchv as a web service at the same endpoint as the OTLP collector, gated by the same auth. v0 team mode: "everyone sees everything," documented as such. Per-user filtering and permissions in v1.
+
+## CLI surface
+
+Complete user-facing commands:
+
+```
+# Setup and lifecycle
+agentlog init [--storage local|r2|s3|custom] [--remote URL]
+agentlog start [--foreground]
+agentlog stop
+agentlog status
+agentlog logs [--follow]
+agentlog config <get|set> <key> [value]
+agentlog migrate --to <backend>
+agentlog sync [--endpoint <url>] [--bucket <name>] [--access-key-id <id>] [--secret-access-key <key>] [--prefix agentlog]
+agentlog autostart <enable|disable|status>
+agentlog doctor [--json]
+agentlog uninstall [--keep-data]
+
+# Capture management
+agentlog reveal <session-id>
+agentlog redact reapply
+agentlog index <pause|resume|status>
+
+# Import
+agentlog import [--source codex-cli|codex-desktop|claude|claude-code-desktop|claude-workspace|claude-sdk|gemini-cli|antigravity|devin-cli|cursor|all] [--since 30d|all] [--repos <list>] [--dry-run]
+agentlog import claude-web --file <path> [--scope local|team]
+agentlog import chatgpt --file <path> [--scope local|team]
+agentlog import status
+
+# Recall
+agentlog recall start
+agentlog recall add-to <codex|claude|gemini|antigravity|cursor>
+agentlog recall reindex
+
+# Viewing
+agentlog history [query] [--web] [--repo <repo>] [--provider <provider>] [--since <duration>] [--include-web-chats]
+agentlog show <session-id> [--json|--path|--open]
+
+# Team mode
+agentlog server
+```
+
+## Setup flows
+
+### Solo, local only (~90 seconds)
+
+```
+brew install agentlog
+agentlog init                    # picks local storage, prompts auto-start
+                                 # → "Start agentlog automatically at login? [Y/n]"
+                                 # → scans for existing history
+                                 # → "Import last 30 days? [Y/n]"
+                                 # → writes launch agent, starts supervisor
+                                 # → import runs in background
+```
+
+After `init` completes, prints:
+
+```
+✓ Launch agent installed at ~/Library/LaunchAgents/com.agentlog.supervisor.plist
+✓ Service started (PID 47291)
+✓ Collector listening on localhost:4318
+✓ Claude Code config updated at ~/.claude/settings.json
+✓ Background import started: 247 sessions queued (~25min)
+
+View your history: `agentlog history`
+Try it out: open Claude Code, have a quick conversation, then run
+`agentlog status` to see it captured.
+```
+
+### Solo, R2-backed (~5 minutes)
+
+```
+brew install agentlog
+agentlog init --storage r2
+# → opens dash.cloudflare.com/?to=/:account/r2/api-tokens
+# → user pastes credentials back into CLI
+# → agentlog creates bucket if needed, validates write
+# → same auto-start and import prompts as above
+```
+
+### Team (afternoon for operator, ~1 minute per developer)
+
+```
+# Operator, once:
+terraform apply              # ships agentlog/deploy-aws or deploy-cloudflare
+                             # outputs OTLP endpoint and bootstrap token
+
+# Each developer:
+agentlog init --remote https://agentlog.myteam.com --token <token>
+                             # auto-start prompt; import scoped to team policy;
+                             # no local OpenObserve (team server runs it)
+```
+
+Companion deployment modules: `agentlog/deploy-aws` (ECS + ALB + S3), `agentlog/deploy-cloudflare` (R2 + Workers for auth proxy), `agentlog/deploy-fly` (Fly.io single-region). The Terraform module is the unsexy linchpin for team adoption.
+
+## Privacy and data handling commitments
+
+Codified because they shape every other decision:
+
+1. **No phone-home telemetry.** agentlog itself ships zero usage analytics anywhere. Any future opt-in metrics live on a separate channel.
+2. **No filesystem scanning.** Only specific known paths: `~/.codex/`, `~/.claude/`, `~/.gemini/`, `~/.local/share/devin/cli/sessions.db`, Cursor's storage, `~/.agentlog/`, plus user-specified import file paths. Windsurf paths are excluded while Cascade transcripts remain encrypted.
+3. **No process inspection beyond `pgrep`.** We check whether Cursor is running. We don't introspect what it's doing.
+4. **Redaction at ingest, not query.** Pattern-matching credentials never land in storage in the first place.
+5. **Reveal is local-only.** Un-redacted content is never reconstructible from team/remote archives.
+6. **Web chats default to local-only.** Even on team-configured installs. Explicit override required to share.
+7. **Agent recall excludes web chats by default.** Human-initiated history viewing includes them.
+8. **Redaction limits are stated honestly.** Pattern-based redaction catches credentials, not sensitive personal content.
+9. **Uninstall removes everything.** Tested.
+
+## What's deferred
+
+- **Web UI beyond cchv** — v0.2 if cchv proves insufficient
+- **Slack notify skill** (`agentlog-slack`) — separate repo, consumes from archive; v0.2
+- **Other web chat sources** (Gemini, Perplexity, Grok) — v1, same pattern, different parsers
+- **Heuristic repo inference for web chats** — v1
+- **Auto-detection of new export files in `~/Downloads/`** — v1
+- **Summary generation / "revival packets"** — v1, only if raw retrieval proves insufficient
+- **Cross-machine session linking** — v1, depends on canonical repo keying landing solid
+- **SSO** — v1, enterprise tier
+- **Per-user permissions for team viewing** — v1
+- **Cursor extension for richer capture** — v1 if SQLite proves too lossy
+- **Windows Service install** — v1, currently Scheduled Task only
+- **Direct integration with Claude.ai/ChatGPT desktop app local stores** — probably never; respect the boundary
+
+## What this is not
+
+- Not a memory-curation product. Memorix and Hindsight occupy that space; agentlog can be their substrate.
+- Not an enterprise observability tool. SigNoz/Datadog/Honeycomb are better and accept the same OTel feeds.
+- Not a session-replay tool.
+- Not a Slack bot. Slack integration is downstream of the archive, intentionally.
+- Not a real-time capture tool for web chats. Those are import-only by design.
+
+## The differentiator
+
+A redaction-first, repo-keyed, S3-compatible archive substrate that the agent itself can query via MCP, with backfill of existing CLI history and import paths for web chats. Every piece exists separately. The value is in composing them under one CLI with a setup flow that doesn't take an afternoon and a privacy story that doesn't require trusting a vendor.
+
+If it's good, it disappears: the user forgets it's running, their agents quietly get smarter at their repos over time, and accumulated debugging knowledge stops evaporating between sessions.
+
+That's v0.2.

package/bin/agentlog-recall.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const { runMcpServer } = require("../src/mcp");
+
+runMcpServer().catch((error) => {
+  console.error(error && error.stack ? error.stack : String(error));
+  process.exitCode = 1;
+});

package/bin/agentlog.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+const { main } = require("../src/cli");
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error(formatCliError(error));
+  process.exitCode = 1;
+});
+
+function formatCliError(error) {
+  if (process.env.AGENTLOG_DEBUG && error?.stack) return error.stack;
+  const message = error?.message || String(error);
+  return /^Error:/i.test(message) ? message : `Error: ${message}`;
+}