agenr 0.8.39 → 0.9.0

package/CHANGELOG.md

@@ -1,16 +1,53 @@
 # Changelog
 
-## [0.8.39] - 2025-02-25
+## 0.9.0 (2026-02-25)
 
 ### Features
-- **ingest:** Add LLM debug logging via `--log-dir`, `--log-all`, and `--sample-rate` flags (#238)
-  - Captures raw LLM prompt input and response output per chunk
-  - Logs dedup before/after entry lists
-  - Best-effort writes, never blocks extraction
-  - Sampling defaults to 1-in-10 files; use `--log-all` for full capture
+- Interactive onboarding wizard for `agenr init` (#170)
+  - Auth setup with API key links and connection testing
+  - Embeddings API key connectivity check during setup
+  - Platform auto-detection for OpenClaw and Codex (macOS, Linux, Windows)
+  - OpenClaw directory confirmation with custom path support
+  - DB isolation prompt for non-default OpenClaw paths (shared vs isolated)
+  - Project slug derivation with interactive edit
+  - Reconfigure mode with "keep current" defaults
+  - Change tracking for auth, model, embeddings, directory, and DB path
+- Global projects map in `~/.agenr/config.json` for OpenClaw and Codex
+  - Keyed by directory path (multiple instances can share the same project slug)
+  - Stores platform, project slug, and optional dbPath per instance
+  - Per-repo platforms (Cursor, Claude Code, Windsurf) unchanged
+- Current config display shows all registered projects with directories and DB isolation status
+- `resolveProjectFromGlobalConfig()` helper for O(1) project lookup by directory
+- Shared DB warning when same project slug and same database across instances
+- Fix: OpenClaw sessionsDir correctly resolves to agents/main/sessions
+- OpenClaw plugin auto-install with gateway restart during wizard
+- Isolated DB path auto-written to OpenClaw plugin config (no manual editing)
+- Session file scanner with recursive discovery, mtime filtering, size totals
+- Cost estimation before ingest using model pricing from @mariozechner/pi-ai
+- "Recent" ingest passes only last-7-day file paths; "full" uses directory glob
+- Bulk ingest integration (--workers 10 --concurrency 1 --whole-file)
+- Post-ingest consolidation prompt (merges near-duplicates from bulk ingest)
+- Watcher daemon setup on macOS with launchd (120s interval)
+- Re-ingest flow on model/auth change: stops watcher, resets DB, re-ingests
+- Expanded setup summary with plugin/ingest/consolidate/watcher status
+- Next steps section for skipped or failed wizard steps
+
+### Changed
+- Refactored setup.ts: extracted `runSetupCore()` for programmatic use
+- Subscription auth methods moved to "Advanced options" submenu
+- Default recommended model changed to gpt-4.1-mini
+- Non-interactive init behavior preserved when CLI flags are provided
+- Skip .gitignore writes for OpenClaw and Codex (not git repos)
+
+### Fixed
+- Test isolation: init wizard tests use isolated config path via `AGENR_CONFIG_PATH`
+- fix(init): `installOpenClawPlugin` no longer forces the `OPENCLAW_HOME`
+  environment variable on OpenClaw CLI calls, preventing production config
+  overwrites when targeting a non-default directory (e.g. sandbox)
+- fix(init): wizard now adds `"agenr"` to `plugins.allow` in the target
+  OpenClaw config, ensuring the plugin is explicitly trusted and suppressing
+  the auto-load warning
 
-### Tests
-- Add tests for ingest debug logging: file creation, sampling, dedup logs, graceful failure on bad logDir
 ## [0.8.40] - 2026-02-25
 
 ### Added

package/README.md

@@ -1,63 +1,72 @@
+```text
+ █████╗  ██████╗ ███████╗███╗   ██╗██████╗
+██╔══██╗██╔════╝ ██╔════╝████╗  ██║██╔══██╗
+███████║██║  ███╗█████╗  ██╔██╗ ██║██████╔╝
+██╔══██║██║   ██║██╔══╝  ██║╚██╗██║██╔══██╗
+██║  ██║╚██████╔╝███████╗██║ ╚████║██║  ██║
+╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝╚═╝  ╚═╝
+  AGENt memoRy
+```
+
 # AGENR
 
 **AY-JEN-ER** - Human memory for AI agents.
 
-Your AI forgets everything between sessions. AGENR fixes that.
+Your AI forgets everything between sessions. AGENR fixes that. It extracts structured knowledge from your conversation transcripts - facts, decisions, preferences, todos, relationships, events, lessons - and stores them in a local database with semantic search. Entries strengthen when reinforced, decay when stale, and resolve contradictions. One local database. Your memory stays on your machine.
 
-It extracts structured knowledge from your OpenClaw conversation transcripts - facts, decisions, preferences, todos, relationships, events, lessons - and stores them in a local database with semantic search. Entries strengthen when reinforced, decay when stale, and resolve contradictions. It's not a search engine. It's memory that gets healthier with use.
+## Quick Start
 
-One local database. Your memory stays on your machine.
+```bash
+pnpm install -g agenr
+agenr init
+```
 
-## What you need
+That's it. The interactive wizard handles everything: auth setup, platform detection, plugin installation, session ingestion, and watcher configuration. Run `agenr init` again anytime to reconfigure.
 
-AGENR uses embeddings to make your memory searchable. The best setup we've found: an **OpenAI API key** with `text-embedding-3-small`. Embeddings cost fractions of a penny per operation - a full ingestion of 100+ session transcripts runs about $0.10 total.
+## What It Does
 
-AGENR also supports **OpenAI Pro subscriptions** and **Anthropic Claude subscriptions** (no API key needed) for the LLM extraction step. But for the best balance of speed, accuracy, and cost, we recommend `gpt-4.1-nano` with an API key. `agenr setup` walks you through all of this.
+- **Extract** - An LLM reads your transcripts and pulls out structured entries. Smart filtering removes noise (tool calls, file contents, boilerplate - about 80% of a typical session) before the LLM sees it. Hedged or unverified agent claims are capped at importance 5 with an `unverified` tag.
+- **Store** - Entries get embedded and compared against existing knowledge. Near-duplicates reinforce existing entries. New information gets inserted. Online dedup catches copies in real-time.
+- **Recall** - Semantic search plus memory-aware ranking. Entries you recall often score higher. Stale entries decay. Contradicted entries get penalized.
+- **Consolidate** - Periodic cleanup: rule-based expiry first, then optional LLM-assisted merging for entries that say the same thing differently.
 
-```bash
-export OPENAI_API_KEY=sk-...  # for embeddings + extraction
+```text
+Transcript -> Filter -> Extract -> Store -> Recall
+               80%       LLM      dedup    semantic
+               noise     typed    + embed  + memory-
+               removed   entries  + dedup    aware
 ```
 
-## Setup
-
-### 1. Install and ingest your history
+## What You Need
 
-```bash
-npm install -g agenr
+An **OpenAI API key** for embeddings (`text-embedding-3-small`). Embeddings cost fractions of a penny per operation - a full ingestion of 100+ session transcripts runs about $0.10 total.
 
-agenr setup        # configure LLM provider + auth
-agenr ingest ~/.openclaw/agents/main/sessions/  # bootstrap from existing sessions
-agenr recall "what did we decide about the database schema?"
-```
+For the LLM extraction step, AGENR supports:
+- **OpenAI API key** (recommended) - `gpt-4.1` is highly recommended for best extraction quality; `gpt-4.1-mini` is the default and works well if cost is a concern; `gpt-4.1-nano` is the budget option
+- **OpenAI Pro subscription** - no API key needed
+- **Anthropic Claude subscription** - no API key needed
 
-### 2. Keep it fresh
+The `agenr init` wizard walks you through all of this.
 
 ```bash
-agenr daemon install   # runs in background, watches your sessions automatically
-agenr daemon status
-agenr daemon logs
+export OPENAI_API_KEY=sk-...  # for embeddings + extraction
 ```
 
-### 3. Wire your agent
+## Platform Setup
 
-Choose your platform:
+### OpenClaw (recommended)
 
-#### OpenClaw (recommended)
+`agenr init` auto-detects OpenClaw, installs the native plugin, and restarts the gateway. The plugin handles everything automatically: three-phase memory injection at session start, mid-session signals when important entries arrive, cross-session handoff summaries, and native `agenr_recall`, `agenr_store`, `agenr_extract`, and `agenr_retire` tools.
 
-The agenr OpenClaw plugin handles everything automatically - memory injection at
-session start, mid-session signals when important new entries arrive, and
-native `agenr_recall`, `agenr_store`, `agenr_extract`, and `agenr_retire`
-tools registered directly in the agent toolset.
+No AGENTS.md edits needed. No MCP config needed. The bundled SKILL.md loads automatically and instructs the agent when to call `agenr_store` proactively.
+
+**Manual alternative:**
 
 ```bash
 openclaw plugins install agenr
 ```
 
-> **Security notice:** OpenClaw's code scanner will flag a critical warning during install: _"Shell command execution detected (child_process)."_ This is expected. agenr shells out to its own CLI binary to run recall and store operations -- it does not make any external network calls, does not read your OpenClaw credentials, and does not send data anywhere. The plugin source is open and auditable at [github.com/agenr-ai/agenr](https://github.com/agenr-ai/agenr).
-
-That's it. Memory injection happens via the plugin's `before_agent_start` hook.
-No AGENTS.md edits needed. The bundled `SKILL.md` loads automatically and
-instructs the agent when to call `agenr_store` proactively.
+> **Security notice:** OpenClaw's code scanner will flag a critical warning during install: _"Shell command execution detected (child_process)."_ This is expected. agenr shells out to its own CLI binary for recall and store operations - it does not make external network calls, does not read your OpenClaw credentials, and does not send data anywhere. The plugin source is open and auditable.
 
 Optional config in `openclaw.json`:
 
@@ -78,20 +87,25 @@ Optional config in `openclaw.json`:
 }
 ```
 
-Signal config controls how often mid-session notifications fire. See
-[docs/OPENCLAW.md](./docs/OPENCLAW.md) for all available options.
+Signal config controls how often mid-session notifications fire. See [docs/OPENCLAW.md](./docs/OPENCLAW.md) for all available options.
 
-#### Claude Code
+### Claude Code
 
 ```bash
 agenr init --platform claude-code
 ```
 
-Adds the `agenr_recall`/`agenr_store` instruction block to
-`~/.claude/CLAUDE.md` and wires `~/.mcp.json`. Your agent sees the tools and
-knows when to use them.
+Adds the `agenr_recall`/`agenr_store` instruction block to `~/.claude/CLAUDE.md` and wires `~/.mcp.json`.
+
+### Codex
+
+```bash
+agenr init --platform codex
+```
+
+Adds instructions to `~/.codex/AGENTS.md` and wires `~/.codex/config.toml`.
 
-#### Cursor
+### Cursor
 
 ```bash
 agenr init --platform cursor
@@ -99,28 +113,29 @@ agenr init --platform cursor
 
 Adds instructions to `.cursor/rules/agenr.mdc` and wires `.cursor/mcp.json`.
 
-#### Codex
+### Windsurf
 
 ```bash
-agenr init --platform codex
+agenr init --platform windsurf
 ```
 
-Adds instructions to `~/.codex/AGENTS.md` and wires `.mcp.json`.
+Adds instructions to `~/.codeium/windsurf/memories/global_rules.md` and wires `.mcp.json`.
 
-#### Any MCP-compatible tool
+### Generic / Any MCP Tool
 
 ```bash
 agenr init   # auto-detects platform, falls back to generic AGENTS.md
 ```
 
-Or configure manually: start `agenr mcp` as a stdio MCP server. Your agent gets
-`agenr_recall`, `agenr_store`, `agenr_extract`, and `agenr_retire` as tools.
+Or start `agenr mcp` as a stdio MCP server and configure it in your tool's MCP settings manually. Your agent gets `agenr_recall`, `agenr_store`, `agenr_extract`, and `agenr_retire` as tools.
 
-## What happens when you ingest
+## How Memory Works
 
-AGENR reads your OpenClaw session transcripts, filters out noise (tool calls, file dumps, boilerplate - about 80% of a typical session), and extracts structured knowledge entries:
+### Extraction & Storage
 
-```
+AGENR reads your session transcripts, filters out noise, and extracts structured knowledge entries. Each entry has a type, subject, content, importance, and expiry. Near-duplicates are caught automatically - if you discussed the same decision in three sessions, you get one entry with higher confirmations, not three copies.
+
+```bash
 agenr ingest ~/.openclaw/agents/main/sessions/ --glob '**/*.jsonl'
 
 [1/108] session-abc123.jsonl (1.2MB) - 12 extracted, 10 stored, 1 skipped (duplicate), 1 reinforced
@@ -128,7 +143,7 @@ agenr ingest ~/.openclaw/agents/main/sessions/ --glob '**/*.jsonl'
 ...
 ```
 
-Each entry has a type, subject, content, importance, and expiry. Near-duplicates are caught automatically - if you discussed the same decision in three sessions, you get one entry with higher confirmations, not three copies.
+### Recall (semantic + memory-aware)
 
 ```bash
 agenr recall "package manager"
@@ -141,79 +156,108 @@ agenr recall "package manager"
    tags: tooling, package-manager
 ```
 
-## Live watching
+Recall supports date range queries (`--since 14d --until 7d`) and temporal browse mode (`--browse --since 1d`) for recency-ordered lookups without embedding API calls.
 
-The watcher keeps your memory current as you work. It tails your session files, extracts new knowledge every few minutes, and stores it. If you ingested history first, watch resumes right where ingest left off - no re-processing.
+### Cross-session Handoff
+
+When you start a new session, the OpenClaw plugin runs a three-phase context injection:
+
+1. **Phase 1A** - Reads the last 7 user+assistant turns from the most recent session file for immediate continuity
+2. **Phase 1B** - Runs browse-mode recall for the last 24 hours, picking up importance-10 handoff entries written when the previous session ended
+3. **Phase 2** - Semantic recall seeded from Phase 1A turns plus the first user message, deduplicated against Phase 1B results
+
+When a session ends, the plugin builds a merged transcript from the current and prior sessions, summarizes it via LLM into a structured handoff entry at importance 10, and stores it. The next session consumes and retires the handoff entry after use.
+
+A two-phase storage strategy prevents race conditions: Phase 1 stores a raw fallback immediately, then Phase 2 asynchronously upgrades it to the LLM summary and retires the fallback.
+
+### Consolidation
+
+Periodic cleanup merges near-duplicates and expires stale entries. Run manually or let the init wizard prompt you after a bulk ingest:
 
 ```bash
-# Watch your OpenClaw sessions directory (auto-resolves the default path)
-agenr watch --platform openclaw
+agenr consolidate
+```
+
+## Advanced
+
+### Multi-instance & DB Isolation
+
+When running multiple OpenClaw instances (or mixing OpenClaw and Codex), each instance gets registered in a global projects map at `~/.agenr/config.json`. By default, all instances share `~/.agenr/knowledge.db` with data separated by project tags.
 
-# Install as a background daemon (macOS launchd)
-agenr daemon install
-agenr daemon status
-agenr daemon logs
+For non-default OpenClaw paths, the init wizard offers isolated databases:
+
+```text
+~/.agenr/knowledge.db          # shared (default)
+~/my-openclaw/agenr-data/knowledge.db  # isolated
 ```
 
-You can also auto-refresh a context file that AI tools read on startup:
+The wizard writes the isolated DB path directly to the OpenClaw plugin config so no manual editing is needed.
+
+### Manual Ingest
 
 ```bash
-agenr watch --platform openclaw --context ~/.agenr/CONTEXT.md
+agenr ingest <paths...> --bulk --workers 10 --whole-file
 ```
 
-## How it works
+The init wizard offers cost estimation before ingestion using model pricing, showing estimated token counts and costs for recent (last 7 days) vs full history ingestion.
 
-**Extract** - An LLM reads your transcripts and pulls out structured entries: facts, decisions, preferences, todos, relationships, events, lessons. Smart filtering removes noise (tool calls, file contents, boilerplate) before the LLM ever sees it. For OpenClaw sessions, hedged or unverified agent claims are detected and capped at importance 5 with an `unverified` tag - so speculative assistant statements do not pollute your memory as facts.
+### Live Watching & Watcher
 
-**Store** - Entries get embedded and compared against what's already in the database. Near-duplicates reinforce existing knowledge. New information gets inserted. Online dedup catches copies in real-time.
+The watcher tails your session files, extracts new knowledge every few minutes, and stores it. If you ingested history first, watch resumes right where ingest left off.
 
-**Recall** - Semantic search plus memory-aware ranking. Entries you recall often score higher. Stale entries decay. Contradicted entries get penalized.
-
-**Consolidate** - Periodic cleanup: rule-based expiry first, then optional LLM-assisted merging for entries that say the same thing differently.
+```bash
+# Watch your sessions directory
+agenr watch --platform openclaw
 
+# Install as a background daemon (macOS launchd, 120s interval)
+agenr watcher install
+agenr watcher status
+agenr watcher logs
 ```
-Transcript -> Filter -> Extract -> Store -> Recall
-               80%       LLM      dedup    semantic
-               noise     typed    + embed  + memory-
-               removed   entries  + dedup    aware
+
+### Benchmarking
+
+Evaluate extraction quality against scored rubrics:
+
+```bash
+agenr benchmark
 ```
 
-## MCP integration
+Runs extraction against benchmark session fixtures, scores results against rubric JSON, and reports per-session plus overall metrics (recall, partial recall, precision proxy, composite score, pass rate). Supports multi-run aggregation with mean/min/stdev reporting.
 
-agenr exposes four MCP tools: `agenr_recall`, `agenr_store`, `agenr_extract`,
-`agenr_retire`.
+### MCP Integration (manual)
 
-**OpenClaw** - `openclaw plugins install agenr` (plugin registers tools
-natively; no MCP config needed)
+If you prefer manual MCP setup over `agenr init`, start the stdio server:
 
-**Claude Code / Cursor / Codex** - `agenr init --platform <name>` (wires MCP
-config and instructions)
+```bash
+agenr mcp
+```
 
-**Manual** - start `agenr mcp` as a stdio server and configure in your tool's
-MCP settings.
+This exposes four tools: `agenr_recall`, `agenr_store`, `agenr_extract`, `agenr_retire`. Configure it in your tool's MCP settings as a stdio server.
 
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `agenr setup` | Interactive configuration (LLM provider, auth, model defaults) |
-| `agenr init [options]` | Wire a project: instructions file + MCP config + project scope. Use `--platform openclaw\|claude-code\|cursor\|codex\|generic` |
+| `agenr init` | Interactive setup wizard: auth, platform detection, plugin install, ingestion, watcher. Replaces the old `setup` flow. Use `--platform` to skip auto-detection. |
+| `agenr setup` | Configure LLM provider, auth, and model defaults (also available inside `init`) |
 | `agenr config` | Show and update agenr configuration |
 | `agenr auth` | Authentication status and diagnostics |
 | `agenr ingest <paths...>` | Bulk-ingest files and directories |
 | `agenr extract <files...>` | Extract knowledge entries from text files |
 | `agenr store [files...]` | Store entries with semantic dedup |
-| `agenr recall [query]` | Semantic + memory-aware recall. Use `--since` / `--until` for date range queries (e.g. `--since 14d --until 7d` for entries from two weeks ago). |
-| `agenr retire [subject]` | Retire a stale entry (hidden, not deleted). Match by subject text or use --id <id> to target by entry ID. |
+| `agenr recall [query]` | Semantic + memory-aware recall. Use `--since`/`--until` for date ranges, `--browse` for temporal mode. |
+| `agenr retire [subject]` | Retire a stale entry (hidden, not deleted). Match by subject or `--id`. |
 | `agenr watch [file]` | Live-watch files/directories, auto-extract knowledge |
-| `agenr daemon install` | Install background watch daemon (macOS launchd) |
-| `agenr daemon status` | Show daemon status (running/stopped, pid, watched file, recent logs) |
-| `agenr daemon logs [--lines <n>] [--follow]` | Stream or show recent daemon logs for troubleshooting |
+| `agenr watcher install` | Install background watch daemon (macOS launchd) |
+| `agenr watcher status` | Show daemon status (running/stopped, pid, watched file, recent logs) |
+| `agenr watcher logs` | Stream or show recent daemon logs |
 | `agenr consolidate` | Clean up and merge near-duplicates |
+| `agenr benchmark` | Run extraction against benchmark fixtures and score results |
 | `agenr context` | Generate context file for AI tool integration |
 | `agenr health` | Show database health and forgetting candidates |
 | `agenr mcp` | Start MCP server (stdio) |
-| `agenr todo <subcommand> <subject>` | Manage todos in the knowledge base |
+| `agenr todo <subcommand>` | Manage todos in the knowledge base |
 | `agenr db <cmd>` | Database management (stats, version, export, reset, path, check, rebuild-index) |
 
 Full reference: [docs/CLI.md](./docs/CLI.md) | [docs/CONFIGURATION.md](./docs/CONFIGURATION.md)
@@ -221,20 +265,20 @@ Full reference: [docs/CLI.md](./docs/CLI.md) | [docs/CONFIGURATION.md](./docs/CO
 ## Architecture
 
 - **Runtime:** Node.js 20+, TypeScript, ESM
-- **Storage:** libsql/SQLite (`~/.agenr/knowledge.db`)
+- **Storage:** libsql/SQLite - default at `~/.agenr/knowledge.db`, optionally isolated per instance
 - **Embeddings:** OpenAI `text-embedding-3-small`, 1024 dimensions
 - **Recall scoring:** Vector similarity x recency x memory strength (max(importance, recall strength)), with contradiction penalties
+- **Global config:** `~/.agenr/config.json` - stores auth, model, and a projects map keyed by directory path with platform, project slug, and optional isolated DB path per instance
 
 Deep dive: [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)
 
 ## Status
 
-The core pipeline is stable and tested (841 tests). We use it daily managing
-thousands of knowledge entries across OpenClaw sessions.
+The core pipeline is stable and tested. We use it daily managing thousands of knowledge entries across OpenClaw sessions.
 
-What works: extraction, storage, recall, MCP integration, online dedup, consolidation, smart filtering, live watching, daemon mode.
+**Shipped:** extraction, storage, recall (semantic + browse), MCP integration, online dedup, consolidation, smart filtering, live watching, daemon mode, cross-session handoff (LLM-summarized), three-phase context injection, interactive init wizard, cost estimation, DB isolation, benchmarking.
 
-What's next: GUI Management Console (browse, search, and curate your knowledge database visually), Cursor live signals, Claude Code UserPromptSubmit adapter, transitive project dependencies.
+**Next:** GUI Management Console (browse, search, and curate your knowledge database visually), Cursor live signals, Claude Code UserPromptSubmit adapter, transitive project dependencies.
 
 ## Philosophy
 
@@ -248,10 +292,14 @@ AGENR keeps your memory on your machine because it is yours. It's structured (no
 
 | Problem | Fix |
 |---|---|
+| `agenr init` wizard fails to detect platform | Pass `--platform openclaw` (or `codex`, `claude-code`, etc.) explicitly |
+| Plugin install fails during wizard | Run `openclaw plugins install agenr` manually, then `openclaw gateway restart` |
 | Embeddings fail | Set `OPENAI_API_KEY` env var or `agenr config set-key openai <key>` |
 | Database locked | Wait for consolidation to finish, or check `~/.agenr/consolidation.lock` |
 | Recall returns nothing after force-kill | `agenr db rebuild-index` (vector index corruption) |
 | Extraction fails mid-file | Retry - dedup skips already-stored entries |
+| Stale handoff entries persist | Run `agenr recall --browse --since 1d` to check, then `agenr retire --id <id>` |
+| Gateway doesn't pick up plugin | Run `openclaw gateway restart` after plugin install |
 
 ## License