agenr 2.1.0 → 3.1.0
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.
- package/CHANGELOG.md +65 -0
- package/LICENSE +21 -661
- package/README.md +48 -25
- package/dist/adapters/openclaw/index.d.ts +1 -1
- package/dist/adapters/openclaw/index.js +533 -2260
- package/dist/adapters/skeln/index.d.ts +1951 -0
- package/dist/adapters/skeln/index.js +3964 -0
- package/dist/chunk-E2DHUFZK.js +2660 -0
- package/dist/{chunk-DGV6D6Q3.js → chunk-EEEL53X4.js} +3547 -4479
- package/dist/chunk-GELCEVFA.js +14 -0
- package/dist/chunk-JSVQILB3.js +1207 -0
- package/dist/{chunk-7TDALVPY.js → chunk-NNO2V4GH.js} +5139 -4635
- package/dist/{chunk-MJIB6J5S.js → chunk-NOIZQRQV.js} +6 -4
- package/dist/{chunk-IMQIJPIP.js → chunk-V5CDMHRN.js} +48 -60
- package/dist/claim-slot-policy-CdrW_1l4.d.ts +13 -0
- package/dist/cli.js +19 -17
- package/dist/core/recall/index.d.ts +5 -14
- package/dist/core/recall/index.js +1 -1
- package/dist/internal-eval-server.js +5 -4
- package/dist/internal-recall-eval-server.js +5 -4
- package/dist/{ports-Nj5nd2Ri.d.ts → ports-CpzWESmZ.d.ts} +208 -2
- package/package.json +8 -6
- /package/dist/{chunk-6T5RXGIR.js → chunk-5LADPJ4C.js} +0 -0
package/README.md
CHANGED
|
@@ -18,7 +18,7 @@ agenr gives agents a persistent brain: a local SQLite database of durable knowle
|
|
|
18
18
|
|
|
19
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.
|
|
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
|
|
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/agenr-plugin`) and the Skeln extension (`@agenr/skeln-plugin`). The CLI provides offline ingest, recall, and maintenance against that same database.
|
|
22
22
|
|
|
23
23
|
## Features
|
|
24
24
|
|
|
@@ -28,11 +28,12 @@ What makes agenr different is the combination of local-first storage, semantic e
|
|
|
28
28
|
- LLM-powered knowledge extraction from conversation transcripts.
|
|
29
29
|
- Semantic deduplication using exact hashes, normalized hashes, embeddings, and within-run clustering.
|
|
30
30
|
- Session continuity with predecessor resolution, recent transcript tails, and LLM-generated continuity summaries.
|
|
31
|
-
- Surgeon maintenance passes for corpus health:
|
|
32
|
-
- Agent tools for `store`, `recall`, `retire`, `update`, and `trace`
|
|
31
|
+
- Surgeon maintenance passes for corpus health: claim-key quality, proposal resolution, supersession review, and retirement cleanup, all with audit history.
|
|
32
|
+
- Agent tools for durable memory through the OpenClaw plugin (`store`, `recall`, `retire`, `update`, and `trace`) and the Skeln plugin (`store`, `recall`, `update`, `work`, and goal aliases).
|
|
33
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.
|
|
34
35
|
- Local-first storage with SQLite/libSQL. Memory stays on your machine; only model and embedding calls leave it.
|
|
35
|
-
- Designed for multi-agent systems so future adapters can share the same database.
|
|
36
|
+
- Designed for multi-agent systems so OpenClaw, Skeln, and future adapters can share the same database.
|
|
36
37
|
|
|
37
38
|
## Quick Start - The Recommended Way
|
|
38
39
|
|
|
@@ -67,7 +68,7 @@ The OpenClaw plugin id remains `agenr`, so `plugins.entries.agenr`, `plugins.slo
|
|
|
67
68
|
After the plugin is installed, `openclaw plugins update agenr` continues to target that same plugin id.
|
|
68
69
|
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`.
|
|
69
70
|
|
|
70
|
-
If you want to pin an exact plugin release, install a versioned package spec such as `openclaw plugins install @agenr/agenr-plugin@
|
|
71
|
+
If you want to pin an exact plugin release, install a versioned package spec such as `openclaw plugins install @agenr/agenr-plugin@3.0.0`.
|
|
71
72
|
|
|
72
73
|
For local development or a custom build path, run `pnpm build` first and point OpenClaw at the plugin package root:
|
|
73
74
|
|
|
@@ -96,6 +97,17 @@ Migration note:
|
|
|
96
97
|
- Existing users who originally installed the plugin from the `agenr` package should reinstall once with `openclaw plugins install @agenr/agenr-plugin` so OpenClaw records the new npm package source.
|
|
97
98
|
- After that reinstall, `openclaw plugins update agenr` should continue to work because updates key off the plugin id `agenr`.
|
|
98
99
|
|
|
100
|
+
## Quick Start - Skeln Plugin (manual)
|
|
101
|
+
|
|
102
|
+
If you use Skeln instead of OpenClaw, install the Skeln extension after configuring agenr:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
pnpm link --global ./packages/skeln-plugin
|
|
106
|
+
skeln extension add @agenr/skeln-plugin
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
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).
|
|
110
|
+
|
|
99
111
|
## Configuration
|
|
100
112
|
|
|
101
113
|
`agenr init` and `agenr setup` handle configuration interactively. By default, agenr stores config at `~/.agenr/config.json` and the database at `~/.agenr/knowledge.db`.
|
|
@@ -138,23 +150,31 @@ Compatibility policy:
|
|
|
138
150
|
|
|
139
151
|
The CLI surface is still intentionally compact, but it now covers setup, recall, ingest, and corpus maintenance.
|
|
140
152
|
|
|
141
|
-
| Command
|
|
142
|
-
|
|
|
143
|
-
| `agenr init`
|
|
144
|
-
| `agenr setup`
|
|
145
|
-
| `agenr recall <query>`
|
|
146
|
-
| `agenr
|
|
147
|
-
| `agenr ingest
|
|
148
|
-
| `agenr ingest
|
|
149
|
-
| `agenr ingest
|
|
150
|
-
| `agenr
|
|
151
|
-
| `agenr surgeon
|
|
152
|
-
| `agenr surgeon
|
|
153
|
-
| `agenr surgeon
|
|
154
|
-
| `agenr
|
|
153
|
+
| Command | What it does |
|
|
154
|
+
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
155
|
+
| `agenr init` | Interactive first-run wizard: auth, model selection, OpenClaw detection, plugin install, and optional initial ingestion. |
|
|
156
|
+
| `agenr setup` | Configure auth, model defaults, embeddings, and the agenr database path. |
|
|
157
|
+
| `agenr recall <query>` | Run the hybrid recall pipeline with optional temporal and type/tag filters. |
|
|
158
|
+
| `agenr trace` | Inspect one entry's provenance and claim-family lineage by id, subject, or `--last`. |
|
|
159
|
+
| `agenr ingest <path>` | Default durable-entry ingest shorthand. Equivalent to `agenr ingest entries <path>`. |
|
|
160
|
+
| `agenr ingest entries <path>` | Bulk-ingest one file or directory of OpenClaw transcript files into durable knowledge entries. |
|
|
161
|
+
| `agenr ingest episodes [path]` | Backfill episodic summaries from OpenClaw session transcripts, including rotated `.reset.*` and `.deleted.*` files. |
|
|
162
|
+
| `agenr ingest procedures [path]` | Sync repo-authored YAML procedures into procedural-memory revisions stored in the knowledge database. |
|
|
163
|
+
| `agenr surgeon run` | Execute surgeon maintenance. Defaults to the autonomous multi-pass sequence; use `--pass <type>` for one pass. Dry-run by default; add `--apply` to mutate the corpus. |
|
|
164
|
+
| `agenr surgeon status` | Show corpus health, claim-key lifecycle counts, proposal backlog, and the latest surgeon run summary. |
|
|
165
|
+
| `agenr surgeon history` | Show recent surgeon runs. |
|
|
166
|
+
| `agenr surgeon actions <runId>` | Show the audit trail for one surgeon run. |
|
|
167
|
+
| `agenr surgeon backlog` | List open surgeon proposals across runs. |
|
|
168
|
+
| `agenr surgeon proposals <runId>` | Show proposals recorded for one surgeon run. |
|
|
169
|
+
| `agenr surgeon review <proposalId>` | Apply or reject one open proposal. |
|
|
170
|
+
| `agenr scenarios list` | List repo-local claim-key sandbox scenarios. |
|
|
171
|
+
| `agenr scenarios run` | Run one or more claim-key sandbox scenarios. |
|
|
172
|
+
| `agenr db reset` | Delete and recreate the knowledge database. |
|
|
155
173
|
|
|
156
174
|
The OpenClaw plugin also gives the agent five tools directly inside the runtime: `agenr_store`, `agenr_recall`, `agenr_retire`, `agenr_update`, and `agenr_trace`.
|
|
157
175
|
|
|
176
|
+
The Skeln plugin exposes seven tools: `agenr_store`, `agenr_recall`, `agenr_update`, `agenr_work`, `get_goal`, `create_goal`, and `update_goal`. It does not expose `agenr_retire` or `agenr_trace`.
|
|
177
|
+
|
|
158
178
|
Examples:
|
|
159
179
|
|
|
160
180
|
```bash
|
|
@@ -170,12 +190,15 @@ agenr ingest episodes ~/.openclaw/agents/main/sessions/ --recent 30d
|
|
|
170
190
|
# Preview procedure sync changes
|
|
171
191
|
agenr ingest procedures --dry-run
|
|
172
192
|
|
|
173
|
-
# Run the surgeon
|
|
193
|
+
# Run the default autonomous surgeon sequence (dry-run by default)
|
|
174
194
|
agenr surgeon run --budget 2.00
|
|
175
195
|
|
|
176
|
-
# Run
|
|
196
|
+
# Run one explicit surgeon pass
|
|
177
197
|
agenr surgeon run --pass supersession --budget 2.00
|
|
178
198
|
|
|
199
|
+
# Inspect the latest stored entry
|
|
200
|
+
agenr trace --last
|
|
201
|
+
|
|
179
202
|
# Reset the database
|
|
180
203
|
agenr db reset
|
|
181
204
|
```
|
|
@@ -184,7 +207,7 @@ agenr db reset
|
|
|
184
207
|
|
|
185
208
|
- Hexagonal structure: `src/core/` contains pure logic and `src/adapters/` contains infrastructure.
|
|
186
209
|
- The core never imports from adapters or CLI code.
|
|
187
|
-
- OpenClaw, the CLI, and future adapters all target the same underlying memory brain.
|
|
210
|
+
- OpenClaw, Skeln, the CLI, and future adapters all target the same underlying memory brain.
|
|
188
211
|
|
|
189
212
|
See [AGENTS.md](./AGENTS.md) for the full architecture and repository conventions.
|
|
190
213
|
|
|
@@ -204,7 +227,7 @@ The two transcript paths parse OpenClaw transcripts first, but they optimize for
|
|
|
204
227
|
|
|
205
228
|
## How Procedures Work
|
|
206
229
|
|
|
207
|
-
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]`.
|
|
230
|
+
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 entry recall only. For the current model, storage shape, sync semantics, and read surfaces, see [docs/PROCEDURES.md](./docs/PROCEDURES.md).
|
|
208
231
|
|
|
209
232
|
## How Episodes Work
|
|
210
233
|
|
|
@@ -212,7 +235,7 @@ Episodes are session-level memory artifacts stored separately from durable entri
|
|
|
212
235
|
|
|
213
236
|
## How the Surgeon Works
|
|
214
237
|
|
|
215
|
-
The surgeon is a maintenance system for the durable-memory corpus.
|
|
238
|
+
The surgeon is a maintenance system for the durable-memory corpus. Four passes are implemented today: `claim_key_quality`, `proposal_resolution`, `supersession`, and `retirement`. `agenr surgeon run` defaults to an autonomous sequence across those passes and is safe by default because it starts in dry-run mode; `--pass <type>` runs one pass, and `--apply` is the explicit mutation switch. For runtime details, governance, and audit behavior, see [docs/SURGEON.md](./docs/SURGEON.md).
|
|
216
239
|
|
|
217
240
|
## Development
|
|
218
241
|
|
|
@@ -238,4 +261,4 @@ agenr scenarios run --kind store --preserve --verbose
|
|
|
238
261
|
|
|
239
262
|
## License
|
|
240
263
|
|
|
241
|
-
|
|
264
|
+
MIT
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import * as openclaw_plugin_sdk_plugin_entry from 'openclaw/plugin-sdk/plugin-entry';
|
|
2
|
-
import { T as TranscriptPort, P as ParsedTranscript } from '../../ports-
|
|
2
|
+
import { T as TranscriptPort, P as ParsedTranscript } from '../../ports-CpzWESmZ.js';
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
5
|
* Parses OpenClaw JSONL session exports into normalized agenr transcripts.
|