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

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.

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

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

The agenr init wizard walks you through all of this.

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:

Security notice: OpenClaw's code scanner will flag a critical warning during install: "Shell command execution detected (child_process)." This is expected. The plugin still contains limited process-spawn code for compatibility utilities, but core recall, store, extract, retire, and trace flows now run through shared in-process agenr services. It does not 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:

Signal config controls how often mid-session notifications fire. See docs/OPENCLAW.md for all available options.

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

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

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

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

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_extract, agenr_retire, and agenr_update as tools.

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.

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 by distance from a specific date.

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.

Periodic cleanup merges near-duplicates and expires stale entries. Run manually or let the init wizard prompt you after a bulk ingest:

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:

The wizard writes the isolated DB path directly to the OpenClaw plugin config so no manual editing is needed.

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.

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.

Evaluate extraction quality against scored rubrics:

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.

If you prefer manual MCP setup over agenr init, start the stdio server:

This exposes four MCP tools: agenr_recall, agenr_extract, agenr_retire, and agenr_update. Persistent session capture comes from watcher ingestion and platform integrations rather than an MCP agenr_store tool.

Full reference: docs/CLI.md | docs/CONFIGURATION.md

• 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

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, consolidation, 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.

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.

AGPL-3.0 - LICENSE

See CONTRIBUTING.md