█████╗  ██████╗ ███████╗███╗   ██╗██████╗
██╔══██╗██╔════╝ ██╔════╝████╗  ██║██╔══██╗
███████║██║  ███╗█████╗  ██╔██╗ ██║██████╔╝
██╔══██║██║   ██║██╔══╝  ██║╚██╗██║██╔══██╗
██║  ██║╚██████╔╝███████╗██║ ╚████║██║  ██║
╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝╚═╝  ╚═╝
  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 and 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 | Roadmap | Architecture | OpenClaw guide

Quick Start

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, and LLM-assisted retirement, dedup, and contradiction resolution.

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.

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:

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:

{
  "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 for all available options.

Claude Code

agenr init --platform claude-code

Adds the agenr_recall instruction block to ~/.claude/CLAUDE.md and wires .mcp.json.

Codex

agenr init --platform codex

Adds the agenr_recall instruction block to ~/.codex/AGENTS.md and wires ~/.codex/config.toml.

Cursor

agenr init --platform cursor

Adds instructions to .cursor/rules/agenr.mdc and wires .cursor/mcp.json.

Windsurf

agenr init --platform windsurf

Adds instructions to ~/.codeium/windsurf/memories/global_rules.md and wires .mcp.json.

Generic / Any MCP Tool

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.

agenr ingest ~/.openclaw/agents/main/sessions/ --glob '**/*.jsonl'

[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
...

Recall (semantic + memory-aware)

agenr recall "package manager"

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 for the current startup flow and 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:

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:

~/.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

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.

# 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:

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:

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, 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 cleanup status | | 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, vector-check, rebuild-index) |

Full reference: docs/CLI.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

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.

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 vector-check --rebuild (vector shadow-table drift) | | 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

Contributing

See CONTRIBUTING.md