agenr 2026.6.3 → 2026.6.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/CHANGELOG.md +73 -0
  2. package/README.md +47 -205
  3. package/dist/adapters/skeln/index.d.ts +144 -44
  4. package/dist/adapters/skeln/index.js +122 -761
  5. package/dist/{build-before-turn-artifact-NPUHVWFE.js → build-before-turn-artifact-HTCN5SQ5.js} +2 -2
  6. package/dist/{build-recall-artifact-F3LS3PZX.js → build-recall-artifact-F7QFO6VJ.js} +10 -10
  7. package/dist/{chunk-MC3C2XM5.js → chunk-2M2IHL2D.js} +1 -1
  8. package/dist/{chunk-5AYIXQRF.js → chunk-FHWCJZY4.js} +933 -40
  9. package/dist/{chunk-ZX55JBV2.js → chunk-HIBNCMNN.js} +133 -141
  10. package/dist/{chunk-U74RE3L7.js → chunk-JOL2R47V.js} +315 -129
  11. package/dist/{chunk-IBPS64W3.js → chunk-LOL4EZ2U.js} +1 -1
  12. package/dist/{chunk-5TIP2EPP.js → chunk-N7FY6CUJ.js} +196 -188
  13. package/dist/{chunk-VTHBPXDQ.js → chunk-TA35CTKF.js} +13 -12
  14. package/dist/{chunk-XFJ4S4G2.js → chunk-TERUD7SI.js} +91 -94
  15. package/dist/{chunk-SOQW7356.js → chunk-UAR442BF.js} +96 -96
  16. package/dist/{chunk-GAERET5Q.js → chunk-WDIVC5AQ.js} +82 -82
  17. package/dist/{chunk-NSLTJBUC.js → chunk-ZKUJADHI.js} +148 -55
  18. package/dist/{chunk-SIY3JA7T.js → chunk-ZN2D5IX5.js} +989 -196
  19. package/dist/cli.js +2836 -161
  20. package/dist/core/recall/index.d.ts +14 -14
  21. package/dist/core/recall/index.js +3 -3
  22. package/dist/internal-eval-server.js +6 -6
  23. package/dist/internal-recall-eval-server.js +6 -6
  24. package/dist/{lifecycle-checkpoint-IAC5FCQU.js → lifecycle-checkpoint-FQ72JJVF.js} +1 -0
  25. package/dist/{ports-C4QkwDBS.d.ts → ports-D2NfqCo4.d.ts} +33 -33
  26. package/dist/{service-EKFACEN6.js → service-MVUFTC73.js} +3 -3
  27. package/dist/{service-RHNB5AEQ.js → service-PMOV5VZH.js} +509 -73
  28. package/dist/web/assets/index-TxfP3zqE.js +48 -0
  29. package/dist/web/assets/index-mUwR5tns.css +1 -0
  30. package/dist/web/index.html +14 -0
  31. package/package.json +4 -3
  32. package/dist/chunk-OWGQWQUP.js +0 -45
package/CHANGELOG.md CHANGED
@@ -2,6 +2,79 @@
2
2
 
3
3
  ## [Unreleased]
4
4
 
5
+ ## [2026.6.5] - 2026-06-08
6
+
7
+ Web console, dreaming alias audit, and proposal review hardening release.
8
+
9
+ ### Added
10
+
11
+ - **Web operator console.** Added `agenr web`, a local-only browser console for corpus health, dreaming operations, proposal review, memory browsing, procedure editing, and instance switching.
12
+ - **Dreaming claim-key alias audit.** Deep dreaming can now detect possible claim-key aliases using shared lexical and adjudication helpers, with focused mutation planning and regression coverage.
13
+ - **Mixed-key proposal settlement.** Proposal review now supports manual settlement flows for mixed-key proposals, including UI review affordances and service-level validation.
14
+
15
+ ### Changed
16
+
17
+ - **Dreaming review experience** now has clearer action labels, backlog filtering for reviewed proposals, richer live run feedback, improved durable activity history, and tighter proposal diagnostics.
18
+ - **Web console management UX** now exposes structured API validation, same-origin checks, SSE dreaming progress, memory and procedure management services, and reusable frontend primitives for dense operational workflows.
19
+ - **Trace rendering** now includes clearer durable lifecycle and timeline details across CLI and web surfaces.
20
+
21
+ ### Fixed
22
+
23
+ - **Dreaming duplicate handling** now reduces duplicate claim-key extraction and duplicate insert-durable actions during reconcile passes.
24
+ - **Web console quality review issues** fixed durable metadata drawer layout, proposal review layout, dreaming diagnostics structure, and follow-up quality concerns.
25
+ - **Web console build imports** now resolve nested dreaming review panel dependencies during package builds.
26
+ - **Alias audit maintainability** now consolidates claim-key lexical overlap logic into shared core helpers.
27
+
28
+ ### Validation
29
+
30
+ Changes since release `2026.6.4`:
31
+
32
+ - Add the local-only `agenr web` operator console and React SPA
33
+ - Improve web console management UX, memory browsing, procedure editing, and dreaming progress views
34
+ - Add deep-dreaming claim-key alias audit support and shared lexical overlap helpers
35
+ - Add manual settlement for mixed-key proposals
36
+ - Improve dreaming proposal review clarity, action labels, diagnostics, and durable activity history
37
+ - Reduce dreaming duplicate claim-key extraction and duplicate insert-durable actions
38
+ - Address web console quality review findings
39
+ - Keep `pnpm check` green before release
40
+
41
+ ## [2026.6.4] - 2026-06-07
42
+
43
+ OpenClaw working-memory parity, durable terminology cleanup, and claim-key guidance release.
44
+
45
+ ### Added
46
+
47
+ - **OpenClaw working memory.** OpenClaw now exposes the shared working-memory tool surface with Skeln-parity session lifecycle handling and before-prompt working-context injection.
48
+
49
+ ### Changed
50
+
51
+ - **Skeln session working memory** is now decoupled from goals, with session-layer scope resolution, projection readiness, and fork snapshot handling split into focused helpers and tests.
52
+ - **Durable terminology cleanup.** Finished the entry-to-durable rename across store, ingest progress events, eval normalization, adapter helpers, and related types (`StoreDurableDetail`, `TaggedDurable`, `DurableProjectScopeFields`). Removed the before-turn eval `entry` alias on patch items.
53
+ - **Working-memory labels and snapshots** now use exported constants for section labels and snapshot field keys.
54
+ - **README** now presents agenr as local-first memory infrastructure with a simpler quick start, memory-layer map, and host integration table.
55
+ - **Claim-key guidance** now tells agents to use `claimKey` only for slot-like facts that may later be superseded, and to skip it for ordinary facts, decisions, preferences, and lessons.
56
+
57
+ ### Removed
58
+
59
+ - **OpenClaw store nudge system.** Removed mid-session `[MEMORY CHECK]` injection, `storeNudge` plugin config, `MidSessionTracker`, and the `after_tool_call` hook that only existed to feed nudge timing.
60
+
61
+ ### Fixed
62
+
63
+ - **Release validation drift.** Formatted the README and claim-key doctrine updates, then aligned OpenClaw and Skeln tool-guideline regression tests with the stricter claim-key wording.
64
+
65
+ ### Validation
66
+
67
+ Changes since last push to `origin/master`:
68
+
69
+ - Decouple Skeln session working memory from goals
70
+ - Rename durable-memory terminology from entries to durables
71
+ - Remove the OpenClaw store nudge system
72
+ - Add working memory to the OpenClaw plugin with Skeln-parity session lifecycle
73
+ - Export working-memory section label and snapshot field-key constants
74
+ - Rewrite README quick-start and memory-layer documentation
75
+ - Tighten claim-key guidance to slot-like facts only and update regression expectations
76
+ - Keep `pnpm check` green before release
77
+
5
78
  ## [2026.6.3] - 2026-06-06
6
79
 
7
80
  Session-end episode alignment and review hardening release.
package/README.md CHANGED
@@ -10,252 +10,94 @@
10
10
 
11
11
  # agenr
12
12
 
13
- Local-first, durable memory infrastructure for AI agents.
13
+ **Local-first memory for AI agents.** One SQLite brain that survives restarts, tools, and sessions - shared across OpenClaw, Skeln, and the CLI.
14
14
 
15
- ## What is agenr?
15
+ Most runtimes forget what mattered yesterday. agenr keeps memory structured, searchable, and on your machine. Only model and embedding calls leave the box.
16
16
 
17
- agenr gives agents a persistent brain: a local SQLite database of durable knowledge that survives across sessions, tools, and agent restarts. Instead of relying on fragile prompt state or file-based scratch memory, agents can ingest transcripts, extract decisions and lessons, store them as typed entries, generate episodic summaries of what happened, and recall them later with semantic search and memory-aware ranking.
17
+ ## Memory at a glance
18
18
 
19
- It exists because most agent runtimes forget everything important between sessions. Even when a tool has a built-in memory feature, it is often lossy, file-based, or tightly coupled to one surface. agenr keeps memory structured and queryable: facts, decisions, preferences, lessons, milestones, relationships, and session-level episodes live in one local store instead of getting flattened into prompt text.
19
+ agenr splits agent memory into layers. Each answers a different question.
20
20
 
21
- What makes agenr different is the combination of local-first storage, semantic embeddings, hybrid recall, episodic temporal memory, and adapter-friendly architecture. The core is hexagonal, so multiple agent systems can share the same brain over time. Today the production host adapters are the OpenClaw memory plugin (`@agenr/openclaw-plugin`) and the Skeln extension (`@agenr/skeln-plugin`). The CLI provides offline ingest, recall, and maintenance against that same database.
21
+ | Layer | Question | In short |
22
+ | -------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------- |
23
+ | **Durable** | What is true? | Facts, decisions, preferences, lessons - distilled knowledge with claim-key lifecycle and hybrid recall. |
24
+ | **Episodic** | What happened? | Session-level narrative summaries for time-bounded questions like "what did we do last week?" |
25
+ | **Working** | What are we doing right now? | Transient task state - scratchpad, checkpoints, next actions - injected per turn, not durable truth. |
26
+ | **Procedural** | How do I do this? | Repo-authored YAML runbooks synced into the store for repeatable workflows. |
27
+ | **Dreaming** | Is the corpus healthy? | Background maintenance: scan, reconcile, and repair durable memory behind an explicit apply gate. |
22
28
 
23
- ## Features
29
+ **Durable** and **episodic** live in the database. **Working** is session-scoped and fades when the task moves on. **Procedural** is authored in git and synced in. **Dreaming** keeps the long-term store coherent over time.
24
30
 
25
- - Hybrid recall for durable knowledge: vector similarity, lexical FTS, temporal awareness, recency decay, and importance weighting.
26
- - Episodic memory: session-level summaries with temporal filtering and optional semantic episode search for questions like "what happened yesterday?"
27
- - Procedural memory: repo-authored YAML procedures synced into durable structured runbooks for repeatable how-to workflows.
28
- - LLM-powered knowledge extraction from conversation transcripts.
29
- - Semantic deduplication using exact hashes, normalized hashes, embeddings, and within-run clustering.
30
- - Session-end episode ingest for the just-finished OpenClaw session.
31
- - Dreaming maintenance pipeline for corpus health: tiered scan, deterministic reconcile, and apply with audit history.
32
- - Agent tools for durable memory through the OpenClaw plugin (`store`, `recall`, `fetch`, `update`, and `trace`) and the Skeln plugin (`store`, `recall`, `update`, `work`, and goal aliases).
33
- - Native OpenClaw memory plugin that replaces OpenClaw's built-in memory slot.
34
- - Skeln extension with working-memory tools, goal aliases, and shared recall/store semantics.
35
- - Local-first storage with SQLite/libSQL. Memory stays on your machine; only model and embedding calls leave it.
36
- - Designed for multi-agent systems so OpenClaw, Skeln, and future adapters can share the same database.
31
+ Deep dives:
37
32
 
38
- ## Quick Start - The Recommended Way
33
+ - [Durable memory](./docs/DURABLES.md) - store pipeline, claim keys, supersession
34
+ - [Episodes](./docs/EPISODES.md) - session summaries and temporal recall
35
+ - [Working memory](./docs/OPENCLAW-PLUGIN.md#agenr_work) - `agenr_work`, checkpoints, transient context ([Skeln details](./docs/SKELN-PLUGIN.md))
36
+ - [Procedures](./docs/PROCEDURES.md) - authoring, sync, and recall routing
37
+ - [Dreaming](./docs/DREAMING.md) - tiers, scan/reconcile/apply, corpus health
38
+ - [Recall](./docs/RECALL.md) - hybrid search across memory layers
39
+
40
+ ## Quick start
39
41
 
40
42
  ```bash
41
43
  pnpm install -g agenr
42
44
  agenr init
43
45
  ```
44
46
 
45
- That's it. The interactive wizard handles everything.
46
-
47
- It walks through:
48
-
49
- - auth setup for OpenAI API keys, Anthropic API keys, OpenAI subscription auth via Codex CLI, or Anthropic subscription auth via OAuth/token
50
- - model selection filtered by the auth method you chose
51
- - OpenAI embedding key setup
52
- - OpenClaw detection and optional plugin installation
53
- - session scanning and optional bulk ingestion of existing transcripts into durable entries and episodic summaries
54
-
55
- Run `agenr init` again any time you want to re-run onboarding, reinstall the plugin, or ingest another batch of existing sessions.
47
+ The wizard sets up auth, embeddings, your database (`~/.agenr/knowledge.db`), optional OpenClaw plugin install, and an initial transcript ingest pass. Run it again any time to reconfigure or ingest more sessions.
56
48
 
57
- ## Quick Start - OpenClaw Plugin (manual)
58
-
59
- If you already have agenr configured, or you want to install the plugin separately:
49
+ **Manual plugin install**
60
50
 
61
51
  ```bash
52
+ # OpenClaw
62
53
  openclaw plugins install @agenr/openclaw-plugin
63
54
  openclaw gateway restart
64
- ```
65
-
66
- The main `agenr` CLI package does not depend on the OpenClaw SDK at runtime. OpenClaw installs should use the plugin package above.
67
-
68
- `agenr init` normally does this for you, updates `openclaw.json`, and offers an initial ingest pass over existing sessions.
69
- The OpenClaw plugin id remains `agenr`, so `plugins.entries.agenr`, `plugins.slots.memory`, and existing plugin config keys do not change.
70
- After the plugin is installed, `openclaw plugins update agenr` continues to target that same plugin id.
71
- If `plugins.entries.agenr.config` is omitted, the plugin falls back to agenr's normal config resolution: `AGENR_CONFIG_PATH`, then `~/.agenr/config.json`, and the `dbPath` from that config or `~/.agenr/knowledge.db`.
72
-
73
- If you want to pin an exact plugin release, install a versioned package spec such as `openclaw plugins install @agenr/openclaw-plugin@2026.6.1`.
74
-
75
- For local development or a custom build path, run `pnpm build` first and point OpenClaw at the plugin package root:
76
-
77
- ```json
78
- {
79
- "plugins": {
80
- "load": { "paths": ["/path/to/agenr/packages/openclaw-plugin"] },
81
- "allow": ["agenr"],
82
- "slots": { "memory": "agenr" },
83
- "entries": {
84
- "agenr": {
85
- "enabled": true,
86
- "config": {
87
- "dbPath": "~/.agenr/knowledge.db"
88
- }
89
- }
90
- }
91
- }
92
- }
93
- ```
94
-
95
- If `config.json` is not next to `dbPath`, add `"configPath": "/path/to/config.json"` inside `plugins.entries.agenr.config`.
96
55
 
97
- Migration note:
98
-
99
- - Existing users who originally installed the plugin from the `agenr` package should reinstall once with `openclaw plugins install @agenr/openclaw-plugin` so OpenClaw records the new npm package source.
100
- - After that reinstall, `openclaw plugins update agenr` should continue to work because updates key off the plugin id `agenr`.
101
-
102
- ## Quick Start - Skeln Plugin (manual)
103
-
104
- If you use Skeln instead of OpenClaw, install the Skeln extension after configuring agenr:
105
-
106
- ```bash
107
- pnpm link --global ./packages/skeln-plugin
56
+ # Skeln - see docs/SKELN-PLUGIN.md for packaging and config
108
57
  skeln extension add @agenr/skeln-plugin
109
58
  ```
110
59
 
111
- The Skeln extension id is also `agenr`, so runtime config uses `extensions.settings.agenr.*`. For packaging, config, tool surface, and local development details, see [docs/SKELN-PLUGIN.md](./docs/SKELN-PLUGIN.md).
112
-
113
- ## Configuration
114
-
115
- `agenr init` and `agenr setup` handle configuration interactively. By default, agenr stores config at `~/.agenr/config.json` and the database at `~/.agenr/knowledge.db`.
116
-
117
- Overrides:
118
-
119
- - `AGENR_CONFIG_DIR` changes the default config directory.
120
- - `AGENR_CONFIG_PATH` points directly at a specific `config.json`.
121
- - `AGENR_DB_PATH` overrides the database path.
122
-
123
- When agenr runs as an OpenClaw plugin, both `configPath` and `dbPath` are optional overrides. If you omit them, agenr uses its normal config resolution: `AGENR_CONFIG_PATH`, then `~/.agenr/config.json`, and the `dbPath` from that config or `~/.agenr/knowledge.db`.
124
-
125
- Key config fields:
126
-
127
- | Field | What it does |
128
- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
129
- | `auth` | Authentication method: `openai-api-key`, `openai-subscription`, `anthropic-api-key`, `anthropic-oauth`, or `anthropic-token`. |
130
- | `provider` / `model` | Default LLM provider and model used for extraction tasks unless overridden. |
131
- | `credentials` | Stored manual credentials. Today that can include `openaiApiKey`, `anthropicApiKey`, and `anthropicOauthToken`. The config file is written with locked-down permissions (`0600`). |
132
- | `credentials.openaiApiKey` | OpenAI key used for embeddings, and also for extraction when `auth` is `openai-api-key`. Agenr no longer reads legacy `embeddingApiKey` or `apiKey` fields. |
133
- | `embeddingModel` | Embedding model. Defaults to `text-embedding-3-small`. |
134
- | `extractionModel` / `dedupModel` | Optional per-pipeline overrides so extraction and dedup can use different provider/model pairs. |
135
- | `extractionContext` | Optional user context injected into extraction prompts to help the model decide what is worth remembering. |
136
- | `dbPath` | Knowledge database location. Defaults to `~/.agenr/knowledge.db` unless overridden. |
137
-
138
- Important: when agenr is running as an OpenClaw plugin, session summaries and store-time claim extraction use OpenClaw's configured LLM auth, not agenr's. Agenr's config is still required for embeddings and for CLI-based ingestion/recall.
139
-
140
- Compatibility policy:
141
-
142
- - Agenr only supports the current `config.json` shape. Move any legacy `apiKey` value into `credentials.openaiApiKey` or `credentials.anthropicApiKey`, move any `embeddingApiKey` value into `credentials.openaiApiKey`, then remove the legacy fields.
143
- - Agenr only supports fresh databases created by the current schema. Run `agenr db reset` before upgrading when the knowledge database predates the current shape.
144
-
145
- ## What You Need
146
-
147
- - An OpenAI API key for embeddings. Agenr uses `text-embedding-3-small`, and embedding cost is typically fractions of a penny.
148
- - For LLM extraction, one of: an OpenAI API key, OpenAI subscription auth via Codex CLI, an Anthropic API key, or Anthropic subscription auth via OAuth/token.
149
- - `agenr init` handles all of this interactively.
150
-
151
- ## CLI Commands
152
-
153
- The CLI surface is still intentionally compact, but it now covers setup, recall, ingest, and corpus maintenance.
154
-
155
- | Command | What it does |
156
- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
157
- | `agenr init` | Interactive first-run wizard: auth, model selection, OpenClaw detection, plugin install, and optional initial ingestion. |
158
- | `agenr setup` | Configure auth, model defaults, embeddings, and the agenr database path. |
159
- | `agenr recall <query>` | Run the hybrid recall pipeline with optional temporal and type/tag filters. |
160
- | `agenr trace` | Inspect one entry's provenance and claim-family lineage by id, subject, or `--last`. |
161
- | `agenr ingest <path>` | Default durable-entry ingest shorthand. Equivalent to `agenr ingest durables <path>`. |
162
- | `agenr ingest durables <path>` | Bulk-ingest one file or directory of OpenClaw transcript files into durable knowledge entries. |
163
- | `agenr ingest episodes [path]` | Backfill episodic summaries from OpenClaw session transcripts, including rotated `.reset.*` and `.deleted.*` files. |
164
- | `agenr ingest procedures [path]` | Sync repo-authored YAML procedures into procedural-memory revisions stored in the knowledge database. |
165
- | `agenr dream run` | Execute a dreaming maintenance run. Dry-run by default; add `--apply` to mutate the corpus. Use `--tier light`, `standard`, or `deep`. |
166
- | `agenr dream status` | Show corpus health, claim-key lifecycle counts, and the latest dreaming run summary. |
167
- | `agenr dream history` | Show recent dreaming runs. |
168
- | `agenr scenarios list` | List repo-local claim-key sandbox scenarios. |
169
- | `agenr scenarios run` | Run one or more claim-key sandbox scenarios. |
170
- | `agenr db reset` | Delete and recreate the knowledge database. |
171
-
172
- The OpenClaw plugin gives the agent four tools directly inside the runtime: `agenr_store`, `agenr_recall`, `agenr_fetch`, and `agenr_update`.
173
-
174
- The Skeln plugin exposes eight tools: `agenr_store`, `agenr_recall`, `agenr_fetch`, `agenr_update`, `agenr_work`, `get_goal`, `create_goal`, and `update_goal`. Neither host exposes a runtime trace tool; use `agenr trace` for provenance inspection.
175
-
176
- Examples:
60
+ **Try recall from the CLI**
177
61
 
178
62
  ```bash
179
- # Recall knowledge
180
63
  agenr recall "what decisions did we make about the API?"
181
-
182
- # Ingest transcripts into durable entries
183
- agenr ingest ~/.openclaw/agents/main/sessions/
184
-
185
- # Backfill episodic summaries
186
- agenr ingest episodes ~/.openclaw/agents/main/sessions/ --recent 30d
187
-
188
- # Preview procedure sync changes
189
- agenr ingest procedures --dry-run
190
-
191
- # Run a standard-tier dreaming pass (dry-run by default)
192
- agenr dream run --tier standard
193
-
194
- # Apply dreaming mutations explicitly
195
- agenr dream run --tier standard --apply
196
-
197
- # Inspect the latest stored entry
198
- agenr trace --last
199
-
200
- # Reset the database
201
- agenr db reset
64
+ agenr ingest ~/.openclaw/agents/main/sessions/ # durable extraction
65
+ agenr ingest episodes --recent 30d # episodic backfill
66
+ agenr dream status # corpus health
202
67
  ```
203
68
 
204
- ## Architecture
205
-
206
- - Hexagonal structure: `src/core/` contains pure logic and `src/adapters/` contains infrastructure.
207
- - The core never imports from adapters or CLI code.
208
- - OpenClaw, Skeln, the CLI, and future adapters all target the same underlying memory brain.
209
-
210
- See [AGENTS.md](./AGENTS.md) for the full architecture and repository conventions.
211
-
212
- ## How Recall Works
69
+ Full CLI reference: [AGENTS.md](./AGENTS.md#cli-surface).
213
70
 
214
- Recall is a hybrid pipeline. Agenr embeds the query, retrieves candidates through both vector search and SQLite FTS, merges those candidates, then scores them using lexical overlap, vector similarity, recency/around-date logic, and entry importance before returning the final ranking. Temporal filters like `--since` and `--until` are hard filters; `--around` is a ranking bias. Details: [docs/RECALL.md](./docs/RECALL.md).
71
+ ## Host integrations
215
72
 
216
- ## How Ingestion Works
73
+ | Host | Package | Agent tools |
74
+ | -------- | ------------------------ | -------------------------------------------------------------------------- |
75
+ | OpenClaw | `@agenr/openclaw-plugin` | `agenr_store`, `agenr_recall`, `agenr_fetch`, `agenr_update`, `agenr_work` |
76
+ | Skeln | `@agenr/skeln-plugin` | above + `get_goal`, `create_goal`, `update_goal` |
217
77
 
218
- Agenr has two transcript-ingest pipelines plus one repo-authored procedure sync path:
78
+ Both plugins share the same database and recall brain. Details: [OpenClaw plugin](./docs/OPENCLAW-PLUGIN.md), [Skeln plugin](./docs/SKELN-PLUGIN.md).
219
79
 
220
- - `agenr ingest durables <path>` extracts durable typed knowledge such as facts, decisions, preferences, lessons, milestones, and relationships.
221
- - `agenr ingest episodes [path]` generates one narrative summary per session so the brain can answer temporal questions like "what happened last week?"
222
- - `agenr ingest procedures [path]` validates and syncs repo-authored procedural workflows from `procedures/` into the database.
80
+ ## Documentation
223
81
 
224
- The two transcript paths parse OpenClaw transcripts first, but they optimize for different outputs: durable ingest distills long-term knowledge and runs semantic dedup across the whole ingest batch, while episode ingest does a session-by-session preflight pass, uses `sessions.json` metadata when available, reconstructs missing surface metadata for rotated files, and writes episodic summaries. Procedure sync is different: it reads strict YAML authoring files, normalizes them into canonical stored revisions, and writes only when a procedure is new or semantically changed. Details: [docs/INGEST.md](./docs/INGEST.md), [docs/DURABLES.md](./docs/DURABLES.md), and [docs/PROCEDURES.md](./docs/PROCEDURES.md).
82
+ | Topic | Doc |
83
+ | ------------------------------- | ---------------------------------------------- |
84
+ | Architecture and repo shape | [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) |
85
+ | Ingest pipelines | [docs/INGEST.md](./docs/INGEST.md) |
86
+ | Configuration and env overrides | `agenr setup` or `agenr init` |
87
+ | Contributing / development | [AGENTS.md](./AGENTS.md) |
88
+ | Debugging | [docs/DEBUGGING.md](./docs/DEBUGGING.md) |
225
89
 
226
- ## How Procedures Work
227
-
228
- Procedures are the durable how-to layer. They are authored in `procedures/` as reviewed YAML, normalized into canonical stored procedure revisions, and synced with `agenr ingest procedures [path]`. Procedure recall is live through unified host-plugin `agenr_recall` and before-turn suggestion, but the standalone CLI `agenr recall` command still targets durable recall only. For the current model, storage shape, sync semantics, and read surfaces, see [docs/PROCEDURES.md](./docs/PROCEDURES.md).
229
-
230
- ## How Episodes Work
231
-
232
- Episodes are session-level memory artifacts stored separately from durable entries. They preserve temporal narrative: what happened in a session, when it happened, which agent/session it belonged to, and optionally an embedding for semantic episode search. Recall can route narrative or time-bounded questions toward episodes automatically, or combine episode and entry results in mixed mode. For implementation details and the episode recall model, see [docs/EPISODES.md](./docs/EPISODES.md).
233
-
234
- ## How Dreaming Works
235
-
236
- Dreaming is the maintenance system for the durable-memory corpus. Milestone 1 ships a pipeline skeleton with `scan`, deterministic `reconcile`, and `apply`. `agenr dream run` is dry-run by default; `--apply` is the explicit mutation switch, and `--tier` selects `light`, `standard`, or `deep` coverage. For runtime details, governance, and the stage roadmap, see [docs/DREAMING.md](./docs/DREAMING.md).
90
+ Config lives at `~/.agenr/config.json` by default. Override with `AGENR_CONFIG_PATH`, `AGENR_CONFIG_DIR`, or `AGENR_DB_PATH`.
237
91
 
238
92
  ## Development
239
93
 
240
94
  ```bash
241
95
  pnpm install
242
96
  pnpm build
243
- pnpm typecheck:tests
244
- pnpm test
245
- pnpm check # format + lint + source typecheck + test
246
- pnpm internal:recall-eval-server
247
- agenr scenarios run --kind store --preserve --verbose
97
+ pnpm check # format, lint, typecheck, test
248
98
  ```
249
99
 
250
- ## Troubleshooting
251
-
252
- | Problem | What to check |
253
- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
254
- | `agenr init` cannot complete setup | Re-run `agenr setup` and verify the selected auth method is actually available. Subscription flows depend on the relevant external login being present, and non-OpenAI extraction setups still need a separate OpenAI embedding key. |
255
- | `openclaw plugins install @agenr/openclaw-plugin` fails | Make sure the `openclaw` CLI is installed and on `PATH`. For local development, run `pnpm build` and use `plugins.load.paths` instead. |
256
- | `agenr recall` or `agenr_recall` fails with embedding/auth errors | Embeddings always use OpenAI. Confirm `credentials.openaiApiKey` is configured, or re-run `agenr setup` to set the embedding key explicitly. |
257
- | SQLite says the database is locked | Avoid running multiple writers against the same DB at once. Stop overlapping ingest/reset runs, restart the OpenClaw gateway if needed, then retry. |
258
- | OpenClaw does not pick up the plugin | Restart the gateway, confirm `plugins.slots.memory` is `agenr`, confirm `plugins.allow` contains `agenr`, and for dev installs confirm `plugins.load.paths` points at the built `packages/openclaw-plugin` directory. |
100
+ Sandbox helpers and the full contributor workflow are in [AGENTS.md](./AGENTS.md).
259
101
 
260
102
  ## License
261
103