diff --git a/docs/Architecture.md b/docs/Architecture.md index 072d454..7a84253 100644 --- a/docs/Architecture.md +++ b/docs/Architecture.md @@ -297,7 +297,7 @@ does not stop at gates for their own sake. **Approval sources.** Matrix (L5), Gitea comments (D2) and Vikunja comments (O5) are approval sources; each authenticates the approver against its own operator allowlist. The first valid approval wins and is echoed to the other channels. The -knowledge store (L10) is **never** an approval source or an instruction channel. +knowledge vault (L10) is **never** an approval source or an instruction channel. **The trust dial.** How much the operator reviews after the fact is **data the operator sets**, per project and per milestone: for example, whether PR review is @@ -408,16 +408,16 @@ the caller treats it as a failure (L9). - **For a repo:** the project's own documents (`ARCHITECTURE.md`, build plans, conventions), versioned in the repo and changed by PR (D2). Read at work-item start; the repo is the authority. -- **For infrastructure:** the world model in the knowledge store (L10): what +- **For infrastructure:** the world model in the knowledge vault (L10): what exists and how it is arranged. **4. Agent memory** — the agent's own notes, outliving work items and scopes. - **What it holds:** the operator's preferences, lessons learned, recurring decisions and their reasons. Much like a good collaborator's notebook. -- **Where:** the agent's private space in the knowledge store (L10), one note per - fact, with an index. -- **Written by the agent** at defined moments (below); **visible to the operator**, - who corrects it through conversation, not by editing. +- **Where:** the agent's own folder under `memory/` in the knowledge vault (L10), + one note per fact, with an index. Private between agents. +- **Written by the agent** at defined moments (below); **visible to the operator** + (read-only, L10), who corrects it through conversation, not by editing. - **Read at work-item start** (the index, plus notes relevant to the task) and when the agent is about to make a decision the notes cover. @@ -589,38 +589,55 @@ are recorded as input/output pairs from the start, with outcomes marked. Changin a model is then a configuration change and a re-run, not a matter of benchmark chatter. -### L10. Knowledge store (Outline) +### L10. Knowledge vault Durable knowledge that outlives work items: world models, agent memory (L6), and -later operator-written procedures. +operator-written material such as procedures. It is a folder of Markdown files on +the agent host (X1), in the format Obsidian reads (frontmatter, `[[links]]`, +tags), so the operator browses it in Obsidian with links, backlinks and the graph. -**Layout: one writer per document.** -- **One collection per writing principal:** `nisse-ops-world`, `nisse-dev-world`, - each agent's memory, and `procedures` (the operator's). Sharing grants read - access only; concurrent writers never exist. -- **`nisse-dev` gets private space only.** Shared infrastructure documents are a - map of exactly what its sealed network keeps its builds from (D7). -- **Each agent authenticates as its own Outline user,** with its own API token. A - token from the operator's account would silently void every permission here. -- **Collections and documents are identified by ID** from configuration and state, - never discovered, and document IDs recorded when created make writes idempotent. +**One vault, one writer per folder.** +- **Agent memory lives under `memory/`,** one folder per agent. Other folders hold + shared material (world models, the operator's notes); their names and layout are + left to grow with need. +- **Every folder has exactly one writer,** an agent or the operator, so concurrent + writes never happen. +- **Mounts enforce it** (a hard wall, P4): each agent's container gets the folders it + writes read-write, the shared folders it may read read-only, and nothing else. No + agent can read another's memory. `nisse-dev` gets no infrastructure material, + which would be a map of exactly what its builds are kept from (D7). +- **Links point from memory to shared notes, never the other way,** so the shared + part reads cleanly on its own. +- **Writes are atomic** (write, then rename), so a reader never sees half a note. +- **Access is through control tools** (L13): the harness reads and writes the mounted + folders. No tool VM ever sees the vault. +- **History:** the vault is a git repository on the agent host, and the harness + commits each write with the agent and work item that made it. A note's revision is + its commit (L6). + +**The operator's copy.** Syncthing keeps a copy on the operator's devices, with the +direction set per folder: +- **folders an agent writes,** memory included, are send-only from the host: the + operator reads them, and a local edit never flows back; +- **folders the operator writes** are receive-only on the host. + +So conflicts can't arise. Obsidian's own settings folder and `.git` are not synced. **Never an instruction channel, never an approval channel.** Work is never read -out of the knowledge store, and an agent never writes there to make another agent -act. Coordination between agents goes through the operator, Matrix, or a ticket (L1). +out of the vault, and an agent never writes there to make another agent act. +Coordination between agents goes through the operator, Matrix, or a ticket (L1). **Corrections go through conversation.** The operator tells the agent, which -records the correction verbatim (L6). The operator keeps write permission as a -break-glass: stop the agent, edit, restart. An agent re-reads a document's -revision before writing and merges rather than overwrites if it moved. +records the correction verbatim (L6). As a break-glass, the operator can stop the +agent and edit its folder on the host, then restart. **Retrieval is structural first.** Procedures are bound to entries in ops policy -(O2) and fetched whenever a plan uses that entry; search exists in addition, never -instead. +(O2) by path and read whenever a plan uses that entry; search (over plain files) +exists in addition, never instead. -**Outages.** A failed write never blocks work (retry, or record locally and -reconcile). A failed read of a bound procedure stops planning that action; other -failed reads proceed and log the gap. +**Failures.** A failed write never blocks work (retry, or record and reconcile). A +missing bound procedure stops planning that action; other failed reads proceed and +log the gap. ### L11. Prompt injection @@ -1062,8 +1079,8 @@ identity, so every upstream action traces to one agent. ### X5. Supporting services All self-hosted: Matrix (Synapse), Gitea, LiteLLM, the local inference host -(llama-swap on an RTX 4090 host), Vikunja, Outline, Vaultwarden, LLDAP with -Authelia. Each agent gets its own account, scoped token and room in each service +(llama-swap on an RTX 4090 host), Vikunja, Vaultwarden, LLDAP with Authelia, and +Syncthing for the operator's copy of the knowledge vault (L10). Each agent gets its own account, scoped token and room in each service it uses; nothing is shared between agents. --- @@ -1123,11 +1140,13 @@ history): - **Documents as the dev workflow (D2),** a fresh workspace per task and toolchain preflight (D3), and git hygiene learned from the live runs (D4). - **Conversation (L5)** is a first-class requirement, not a command interpreter. +- **The knowledge vault (L10)** replaces Outline: Markdown on the agent host, shared + between agents by mounts, synced to the operator by Syncthing. Revised in PR #90. - **Deployment (X1, L13),** revised in PR #90: one agent host with each agent as a container, and disposable tool VMs (a build VM per project for `nisse-dev`) where every model-chosen command runs over SSH, replacing a VM per agent. - **Kept, largely as they were:** the work model, durability and reconciliation, - LiteLLM and the canonical log, delegation, the knowledge store, prompt injection, + LiteLLM and the canonical log, delegation, prompt injection, identity, and `nisse-ops`' approved step sequences. - **Moved to the Development Plan (to be written):** build order, supporting-service status, and interim arrangements.