OpenAgents

Commit

Document the promotion path beside the knowledge-base corpus

e6f44974b381 · AtlantisPleb · · parent a38b09aa5a08 

Document the promotion path beside the knowledge-base corpus

The corpus had no README and the plugins listing stopped short of it, so the
only written procedure was two prose blocks in build-kb.mjs and src/lib.rs.
Add one, covering what the corpus holds, how a rebuild and a digest re-pin
work, what a stance record carries, and how a stabilized system memory is
drained into a stance.

The drain has two halves in two repositories and they are ordered: the stance
lands here first, or the promotion tombstone in openagents.com points at
nothing. Say so, and say where the boundary is enforced — at promotion, not at
recall, because the two rails are retrieved in different processes and nothing
sees both notes. The reasoning and the refusals live with the code that runs
them, in docs/memory/knowledge-base-boundary.md.

Contract: docs/memory/2026-08-25-system-memory-spec.md section 8.
Part of OpenAgentsInc/openagents#65.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SoZMfWRSGnf6FZX2Ar9rQ2
Co-Authored-By
Claude Fable 5 <noreply@anthropic.com>

Deploy story

What this commit did to the running system — joined from the forge receipt chain, the part a commit page elsewhere cannot show.

pushed
by user · WAL seq 179 · 2026-08-26T01:41:05.564644Z

Changed files

  • modified plugins/README.md
  • added plugins/knowledge-base/README.md

Diff

2 files changed, +72 -0

plugins/README.md modified +6

@@ -33,6 +33,12 @@ OpenAgentsInc/openagents#26 and

33 33 
  whole-file bound. `foreign-sessions` gates its packet entry behind the
34 34 
  default `entry` feature so this crate can depend on the scan logic
35 35 
  without a duplicate-export link error.
36 
- `knowledge-base/` — the retrieval rail rather than a tool: a corpus of
37 
  reviewed stances and public-doc summaries compiled into the artifact at
38 
  build, which the harness queries on every turn and attaches as a bracketed
39 
  note. It declares no mounts and no hosts, and it is never offered to a model
40 
  as a tool. `knowledge-base/README.md` covers the corpus, the rebuild, and how
41 
  a system memory is promoted into a stance.
36 42
37 43 
Each plugin's built `.wasm` artifact and its `sha256:` digest pin are
38 44 
checked in beside the source, so the CLI runs them without a Rust
plugins/knowledge-base/README.md added +66

@@ -0,0 +1,66 @@

1 
# Knowledge base
2
3 
The corpus of reviewed positions and public-doc summaries the coder harness
4 
attaches to a turn, compiled into a WebAssembly plugin the CLI loads.
5
6 
- `kb/stances.json` — the curated stances. Reviewed like content, edited like
7 
  content.
8 
- `build-kb.mjs` — harvests the served docs site into compact entries and
9 
  merges the stances into `kb.json`.
10 
- `src/lib.rs` — the scoring and selection the plugin runs at query time.
11 
- `manifest.json` — the declared interface and the pinned artifact digest.
12
13 
## Rebuilding the corpus
14
15 
```sh
16 
node build-kb.mjs
17 
cargo build --release --target wasm32-unknown-unknown -p knowledge-base
18 
```
19
20 
Then re-pin `artifact.digest` in `manifest.json` to the digest of the rebuilt
21 
`knowledge_base.wasm`. The plugin embeds `kb.json` at build, so a corpus edit
22 
that is not followed by both steps ships nothing.
23
24 
## Adding a stance
25
26 
A stance record carries an `id` (lowercase words joined by hyphens, and the only
27 
stable identifier a stance has), a `title`, the `questions` a reader would ask,
28 
a `state`, the `answer`, the `sources` it rests on, and the `date` it was
29 
reviewed. Scoring weighs `questions` and `title` heaviest, `state` next, and the
30 
`answer` last, so write the questions as a reader would ask them.
31
32 
## Promoting a system memory into a stance
33
34 
The knowledge base owns what the project has reviewed and decided; system memory
35 
owns what the network has observed and can evidence. When a system memory
36 
stabilizes — admitted, unchallenged for a sustained period, repeatedly recalled
37 
— a steward drains it into a stance here, and the memory row is superseded by a
38 
**promotion tombstone** that names the stance. The claim then has exactly one
39 
live home.
40
41 
**Promotion is where the boundary between the two rails is enforced**, because
42 
it is the only place either rail records that a memory and a stance are the same
43 
claim. Recall does not compare them: the knowledge base is retrieved here in the
44 
client, memory recall runs server-side inside `POST /api/v1/responses`, and
45 
nothing sees both notes. Do not add a client-side or request-side suppression
46 
rule without reading the reasoning first.
47
48 
Order matters — add the stance before draining the memory, or the tombstone
49 
points at nothing:
50
51 
1. Add the stance to `kb/stances.json`, citing the memory among its `sources`.
52 
2. Rebuild and re-pin, as above. Land the change through review.
53 
3. Drain the memory with `OpenAgents.Memories.Promotions.promote/3` in
54 
   `OpenAgentsInc/openagents.com`.
55
56 
The full procedure, the refusals, and the reasoning behind the enforcement point
57 
are in `docs/memory/knowledge-base-boundary.md` in that repository. The contract
58 
is `docs/memory/2026-08-25-system-memory-spec.md` section 8 here; the invariant
59 
is MEMORY-012 there.
60
61 
## Tests
62
63 
`src/tests.rs` runs the ranking against the shipped `kb.json`, and
64 
`packages/openagents-cli/test/coder-plugin-knowledge-base.test.ts` proves the
65 
sandboxed artifact and the injected note end to end. Both pin behavior by stance
66 
title, so renaming a title is a test change.

This page updates live while a promote is in flight · changelog