@agenr/openclaw-plugin 0.14.0 → 1.1.0

package/README.md

@@ -1,320 +1,12 @@
-```text
- █████╗  ██████╗ ███████╗███╗   ██╗██████╗
-██╔══██╗██╔════╝ ██╔════╝████╗  ██║██╔══██╗
-███████║██║  ███╗█████╗  ██╔██╗ ██║██████╔╝
-██╔══██║██║   ██║██╔══╝  ██║╚██╗██║██╔══██╗
-██║  ██║╚██████╔╝███████╗██║ ╚████║██║  ██║
-╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝╚═╝  ╚═╝
-  AGENt memoRy
-```
-
-# AGENR
-
-**AY-JEN-ER** - Human memory for AI agents.
-
-This README is the overview and quick start. Canonical mechanism docs live in [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) and [docs/OPENCLAW.md](./docs/OPENCLAW.md).
-
-AGENR is a local, structured, universal, living memory layer for AI agents. It tackles session amnesia, multi-surface fragmentation, and vendor lock-in together so you get one person, many agents, one brain.
-
-It extracts structured knowledge from 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. Your memory stays on your machine.
-
-More: [Vision](./docs/vision.md) | [Roadmap](./docs/roadmap.md) | [Architecture](./docs/ARCHITECTURE.md) | [OpenClaw guide](./docs/OPENCLAW.md)
-
-## Quick Start
-
-```bash
-pnpm install -g agenr
-agenr init
-```
-
-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.
-
-## What It Does
-
-- **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.
-- **Surgeon** - Corpus health maintenance: deterministic cleanup, quality evolution, vector integrity checks, and LLM-assisted retirement, dedup, and contradiction resolution.
-
-```text
-Transcript -> Filter -> Extract -> Store -> Recall
-               80%       LLM      dedup    semantic
-               noise     typed    + embed  + memory-
-               removed   entries  + dedup    aware
-```
-
-## What You Need
-
-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.
-
-For the LLM extraction step, AGENR supports:
-- **OpenAI API key** (recommended) - `gpt-5.4-mini` is the default baseline and recommended balance of quality and cost; `gpt-5.4` is the higher-quality option and the default surgeon model; `gpt-4.1-mini` remains available as a lower-cost fallback
-- **OpenAI Pro subscription** - no API key needed
-- **Anthropic Claude subscription** - no API key needed
-
-The `agenr init` wizard walks you through all of this.
-
-```bash
-export OPENAI_API_KEY=sk-...  # for embeddings + extraction
-```
-
-## Platform Setup
-
-### OpenClaw (recommended)
-
-`agenr init` auto-detects OpenClaw, installs the native plugin, and restarts the gateway. The plugin handles everything automatically: session-start context injection (recent turns, core recall, browse recall, and a memory index), mid-session signals when important entries arrive, cross-session handoff summaries, and native `agenr_recall`, `agenr_store`, `agenr_extract`, `agenr_retire`, `agenr_update`, and session-project tools.
-
-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:** The OpenClaw plugin runs recall, store, extract, retire, update, and trace flows through shared in-process agenr services. It does not shell out to the agenr CLI, read your OpenClaw credentials, or send data anywhere except your configured model and embedding providers. The plugin source is open and auditable.
-
-Optional config in `openclaw.json`:
-
-```json
-{
-  "plugins": {
-    "entries": {
-      "agenr": {
-        "config": {
-          "budget": 2000,
-          "signalMinImportance": 8,
-          "signalCooldownMs": 30000,
-          "signalMaxPerSession": 10
-        }
-      }
-    }
-  }
-}
-```
-
-Signal config controls how often mid-session notifications fire. See [docs/OPENCLAW.md](./docs/OPENCLAW.md) for all available options.
-
-### Claude Code
-
-```bash
-agenr init --platform claude-code
-```
-
-Adds the `agenr_recall` instruction block to `~/.claude/CLAUDE.md` and wires `.mcp.json`.
-
-### Codex
-
-```bash
-agenr init --platform codex
-```
-
-Adds the `agenr_recall` instruction block to `~/.codex/AGENTS.md` and wires `~/.codex/config.toml`.
-
-### Cursor
-
-```bash
-agenr init --platform cursor
-```
-
-Adds instructions to `.cursor/rules/agenr.mdc` and wires `.cursor/mcp.json`.
-
-### Windsurf
-
-```bash
-agenr init --platform windsurf
-```
-
-Adds instructions to `~/.codeium/windsurf/memories/global_rules.md` and wires `.mcp.json`.
-
-### Generic / Any MCP Tool
-
-```bash
-agenr init   # auto-detects platform, falls back to generic AGENTS.md
-```
-
-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`, `agenr_retire`, and `agenr_update` as tools.
-
-## How Memory Works
-
-### 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'
+# @agenr/openclaw-plugin
 
-[1/108] session-abc123.jsonl (1.2MB) - 12 extracted, 10 stored, 1 skipped (duplicate), 1 reinforced
-[2/108] session-def456.jsonl (800KB) - 8 extracted, 7 stored, 0 skipped, 1 reinforced
-...
-```
+Plugin-only npm package for the agenr OpenClaw memory integration.
 
-### Recall (semantic + memory-aware)
+Install it with:
 
 ```bash
-agenr recall "package manager"
+openclaw plugins install @agenr/openclaw-plugin
+openclaw gateway restart
 ```
 
-```text
-1 results (46ms)
-1. [decision] project tooling: We switched this project to pnpm.
-   importance=7 | today | recalled 3 times
-   tags: tooling, package-manager
-```
-
-Recall supports date range queries (`--since 14d --until 7d`), temporal browse mode (`--browse --since 1d`), and around-date targeting (`--around 2026-02-15 --around-radius 14`) to rank entries primarily by distance from a specific date with importance used as a secondary tiebreaker.
-
-### Cross-session Handoff
-
-When you start a new OpenClaw session, agenr injects a startup context assembled from four pieces:
-
-1. **Recent turns** - the last few user/assistant turns from the previous session file for immediate continuity
-2. **Core recall** - universal core memory plus project-tagged core memory for configured `coreProjects`
-3. **Browse recall** - recent high-value memory, scoped by explicit session project when one exists, otherwise limited to universal / NULL-project entries
-4. **Memory index** - a compact breadcrumb list of available projects and memory buckets
-
-The plugin formats those pieces into startup markdown, applies selector and budget limits, and records only the entries that were actually rendered so startup and mid-session recall can dedupe cleanly.
-
-When a session ends, the plugin writes a handoff using a fallback-first strategy: it stores a lightweight fallback entry immediately, then attempts an LLM-upgraded handoff summary. If the LLM upgrade succeeds, the fallback is retired. On the next session start, surfaced handoff entries are consumed and retired after use.
-
-See [docs/OPENCLAW.md](./docs/OPENCLAW.md) for the current startup flow and [docs/OPENCLAW_HANDOFFS.md](./docs/OPENCLAW_HANDOFFS.md) for the detailed handoff lifecycle.
-
-### Corpus Health
-
-The surgeon is the single corpus-health entry point. It runs deterministic pre-steps first, then performs the selected semantic pass. A bare run defaults to a full `auto` sweep:
-
-```bash
-agenr surgeon run --apply
-```
-
-## 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.
-
-For non-default OpenClaw paths, the init wizard offers isolated databases:
-
-```text
-~/.agenr/knowledge.db          # shared (default)
-~/my-openclaw/agenr-data/knowledge.db  # isolated
-```
-
-The wizard writes the isolated DB path directly to the OpenClaw plugin config so no manual editing is needed.
-
-### Manual Ingest
-
-```bash
-agenr ingest <paths...> --bulk --workers 10 --whole-file
-```
-
-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.
-
-### Live Watching & Watcher
-
-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.
-
-```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
-```
-
-### Benchmarking
-
-Evaluate extraction quality against scored rubrics:
-
-```bash
-agenr benchmark
-```
-
-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.
-
-### MCP Integration (manual)
-
-If you prefer manual MCP setup over `agenr init`, start the stdio server:
-
-```bash
-agenr mcp
-```
-
-This exposes five MCP tools: `agenr_recall`, `agenr_store`, `agenr_extract`, `agenr_retire`, and `agenr_update`. Use `agenr_store` for precise structured writes. Watcher ingestion and platform integrations still remain useful for transcript-scale capture.
-
-## Commands
-
-| Command | What it does |
-| --- | --- |
-| `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 ranges, `--around` for target-date ranking, `--browse` for temporal mode. |
-| `agenr retire [subject]` | Retire a stale entry (hidden, not deleted). Match by subject or `--id`. |
-| `agenr update --id <id> [--importance <n>] [--expiry <level>]` | Update mutable entry metadata in place. Supports importance and expiry; pass at least one. |
-| `agenr watch [file]` | Live-watch files/directories, auto-extract knowledge |
-| `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 surgeon run` | Run corpus-health maintenance: cleanup, quality evolution, vector checks, and retirement/dedup/contradictions |
-| `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>` | 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)
-
-## Architecture
-
-- **Runtime:** Node.js 20+, TypeScript, ESM
-- **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. We use it daily managing thousands of knowledge entries across OpenClaw sessions.
-
-**Shipped:** extraction, storage, recall (semantic + browse), MCP integration, online dedup, surgeon corpus health passes, smart filtering, live watching, daemon mode, cross-session handoff (LLM-summarized), three-phase context injection, interactive init wizard, cost estimation, DB isolation, benchmarking.
-
-**Next:** GUI Management Console (browse, search, and curate your knowledge database visually), Cursor live signals, Claude Code UserPromptSubmit adapter, transitive project dependencies.
-
-## Philosophy
-
-The big labs are building bigger brains. agenr is building better continuity.
-
-The product bet is that memory should be local, structured, universal, and living: local because it is yours, structured because "what did we decide?" needs a real answer, universal because it should work across surfaces, and living because stale or contradicted memory must be maintained rather than merely accumulated.
-
-For the product thesis, see [docs/vision.md](./docs/vision.md).
-
-## Troubleshooting
-
-| 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 the active write-heavy command to finish (`agenr ingest --bulk`, `agenr surgeon run --apply`, etc.) and retry |
-| 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
-
-AGPL-3.0 - [LICENSE](./LICENSE)
-
-## Contributing
-
-See [CONTRIBUTING.md](./CONTRIBUTING.md)
+The OpenClaw plugin id remains `agenr`, so existing plugin config keys and memory-slot settings stay the same.