Add rebased OpenClaw x AtoCore V1 review docs
This commit is contained in:
362
docs/openclaw-atocore-v1-architecture.md
Normal file
362
docs/openclaw-atocore-v1-architecture.md
Normal file
@@ -0,0 +1,362 @@
|
||||
# OpenClaw x AtoCore V1 Architecture
|
||||
|
||||
## Purpose
|
||||
|
||||
This document defines the safe V1 operating model for how Discord, Discrawl, OpenClaw, PKM, repos, and AtoCore work together.
|
||||
|
||||
The goal is to let these systems contribute useful signal into AtoCore without turning AtoCore into a raw dump and without blurring trust boundaries.
|
||||
|
||||
## V1 scope
|
||||
|
||||
V1 active inputs are:
|
||||
|
||||
- Discord and Discrawl evidence
|
||||
- OpenClaw interaction evidence
|
||||
- PKM, repos, and KB sources
|
||||
- read-only AtoCore context for comparison and deduplication
|
||||
|
||||
## Core stance
|
||||
|
||||
The V1 stance is simple:
|
||||
|
||||
- Discord and Discrawl are evidence streams.
|
||||
- OpenClaw is the operator and orchestrator.
|
||||
- PKM, repos, and KB tools remain the canonical human and tool truth.
|
||||
- AtoCore memories hold reviewed episodic, personal, and loose project signal.
|
||||
- AtoCore project_state holds the current trusted project answer, manually or tightly gated only.
|
||||
- Future AtoCore entities hold reviewed structured decisions, requirements, constraints, and related facts.
|
||||
|
||||
## Architectural principles
|
||||
|
||||
1. AtoCore remains additive and fail-open from the OpenClaw side.
|
||||
2. Every fact type has exactly one canonical home.
|
||||
3. Raw evidence is not trusted truth.
|
||||
4. Unreviewed signals become evidence or candidates, not active truth.
|
||||
5. Discord-originated paths never directly mutate project_state, registry state, refresh state, ingestion state, or review decisions without explicit human approval.
|
||||
6. OpenClaw is not canonical storage. It retrieves, compares, summarizes, requests approval, and performs approved operator actions.
|
||||
7. The shared operator client is the canonical mutating operator surface. Frontends should reuse it instead of reimplementing AtoCore-calling logic.
|
||||
|
||||
## Explicit approval rule
|
||||
|
||||
In this V1 policy, explicit approval means all of the following:
|
||||
|
||||
- the human directly instructs the specific mutating action
|
||||
- the instruction appears in the current thread or current session
|
||||
- the approval is for that specific action, not vague intent
|
||||
- the approval is not inferred from Discord evidence, Discrawl recall, screener output, or general discussion
|
||||
|
||||
Examples of explicit approval:
|
||||
|
||||
- "refresh p05 now"
|
||||
- "register this project"
|
||||
- "promote that candidate"
|
||||
- "write this to project_state"
|
||||
|
||||
Examples that are not explicit approval:
|
||||
|
||||
- "we should probably refresh this sometime"
|
||||
- "I think this is the current answer"
|
||||
- archived discussion saying a mutation might be useful
|
||||
- a screener report recommending a mutation
|
||||
|
||||
## System roles
|
||||
|
||||
### Discord
|
||||
|
||||
Discord is a live conversational source.
|
||||
It contains fresh context, discussion, uncertainty, and project language grounded in real work.
|
||||
It is not authoritative by itself.
|
||||
|
||||
Discord-originated material should be treated as:
|
||||
|
||||
- raw evidence
|
||||
- candidate material after screening
|
||||
- possible justification for a later human-reviewed promotion into a canonical home
|
||||
|
||||
Discord should never be treated as direct trusted project truth just because someone said it in chat.
|
||||
|
||||
### Discrawl
|
||||
|
||||
Discrawl is a retrieval and archive layer over Discord history.
|
||||
It turns prior conversation into searchable evidence.
|
||||
That is useful for recall, context building, and finding prior decisions or open questions.
|
||||
|
||||
Discrawl is still evidence, not authority.
|
||||
A retrieved Discord thread may show what people thought or said. It does not by itself become trusted project_state.
|
||||
|
||||
### OpenClaw
|
||||
|
||||
OpenClaw is the orchestrator and operator.
|
||||
It is where the human interacts, where approvals happen, and where cross-source reasoning happens.
|
||||
|
||||
OpenClaw's job is to:
|
||||
|
||||
- retrieve
|
||||
- compare
|
||||
- summarize
|
||||
- ask for approval when mutation is requested
|
||||
- call the shared operator client for approved writes
|
||||
- fail open when AtoCore is unavailable
|
||||
|
||||
OpenClaw is not the canonical place where project facts live long-term.
|
||||
|
||||
### PKM
|
||||
|
||||
PKM is a canonical human-authored prose source.
|
||||
It is where notes, thinking, and ongoing project writing live.
|
||||
|
||||
PKM is the canonical home for:
|
||||
|
||||
- project prose notes
|
||||
- working notes
|
||||
- long-form summaries
|
||||
- journal-style project history
|
||||
|
||||
PKM is not the place where OpenClaw should be taught how to operate AtoCore. Operator instructions belong in repo docs and OpenClaw instructions and skills.
|
||||
|
||||
### Repos and KB tools
|
||||
|
||||
Repos and KB tools are canonical human and tool truth for code and structured engineering artifacts.
|
||||
|
||||
They are the canonical home for:
|
||||
|
||||
- source code
|
||||
- repo design docs
|
||||
- structured tool outputs
|
||||
- KB-CAD and KB-FEM facts where those systems are the tool of origin
|
||||
|
||||
### AtoCore memories
|
||||
|
||||
AtoCore memories are for reviewed, durable machine-usable signal that is still loose enough to belong in memory rather than in a stricter structured layer.
|
||||
|
||||
Examples:
|
||||
|
||||
- episodic facts
|
||||
- preferences
|
||||
- identity facts
|
||||
- reviewed loose project facts
|
||||
|
||||
AtoCore memories are not a place to dump raw Discord capture.
|
||||
|
||||
### AtoCore project_state
|
||||
|
||||
AtoCore project_state is the trusted current answer layer.
|
||||
It is the place for questions like:
|
||||
|
||||
- what is the current selected architecture?
|
||||
- what is the current next focus?
|
||||
- what is the trusted status answer right now?
|
||||
|
||||
Because this layer answers current-truth questions, it must remain manually curated or tightly gated.
|
||||
|
||||
### Future AtoCore entities
|
||||
|
||||
Future entities are the canonical home for structured engineering facts that deserve stronger representation than freeform memory.
|
||||
|
||||
Examples:
|
||||
|
||||
- decisions
|
||||
- requirements
|
||||
- constraints
|
||||
- validation claims
|
||||
- structured relationships later
|
||||
|
||||
These should be promoted from evidence or candidates only after review.
|
||||
|
||||
## Logical flow
|
||||
|
||||
```text
|
||||
Discord live chat --.
|
||||
Discrawl archive ----+--> evidence bundle / interactions / screener input
|
||||
OpenClaw evidence ---'
|
||||
|
|
||||
v
|
||||
nightly screener
|
||||
|
|
||||
.--------+--------.
|
||||
v v
|
||||
memory candidates entity candidates (later)
|
||||
| |
|
||||
'--------+--------'
|
||||
v
|
||||
human review in OpenClaw
|
||||
|
|
||||
.-----------------+-----------------.
|
||||
v v v
|
||||
active memory active entity explicit curation
|
||||
|
|
||||
v
|
||||
project_state
|
||||
```
|
||||
|
||||
The load-bearing rule is that review happens before trust.
|
||||
|
||||
## Canonical-home table
|
||||
|
||||
Every named fact type below has exactly one canonical home.
|
||||
|
||||
| Fact type | Canonical home | Why |
|
||||
|---|---|---|
|
||||
| Raw Discord message | Discord / Discrawl archive | It is conversational evidence, not normalized truth |
|
||||
| Archived Discord thread history | Discrawl archive | It is the retrieval form of Discord evidence |
|
||||
| OpenClaw operator instructions | OpenClaw repo docs / skills / instructions | Operating behavior should live in code-adjacent instructions, not PKM |
|
||||
| Project prose notes | PKM | Human-authored project prose belongs in PKM |
|
||||
| Source code | Repo | Code truth lives in version control |
|
||||
| Repo design or architecture doc | Repo | The documentation belongs with the code or system it describes |
|
||||
| Structured KB-CAD / KB-FEM fact | KB tool of origin | Tool-managed structured engineering facts belong in their tool of origin |
|
||||
| Personal identity fact | AtoCore memory (`identity`) | AtoCore memory is the durable machine-usable home |
|
||||
| Preference fact | AtoCore memory (`preference`) | Same reason |
|
||||
| Episodic fact | AtoCore memory (`episodic`) | It is durable recall, not project_state |
|
||||
| Loose reviewed project signal | AtoCore memory (`project`) | Good fit for reviewed but not fully structured project signal |
|
||||
| Engineering decision | Future AtoCore entity (`Decision`) | Decisions need structured lifecycle and supersession |
|
||||
| Requirement | Future AtoCore entity (`Requirement`) | Requirements need structured management |
|
||||
| Constraint | Future AtoCore entity (`Constraint`) | Constraints need structured management |
|
||||
| Current trusted project answer | AtoCore `project_state` | This layer is explicitly for current trusted truth |
|
||||
| Project registration metadata | AtoCore project registry | Registry state is its own canonical operator layer |
|
||||
| Review action (promote / reject / invalidate) | AtoCore audit trail / operator action log | Review decisions are operator events, not source facts |
|
||||
|
||||
## What this means for Discord-originated facts
|
||||
|
||||
A Discord-originated signal can end in more than one place, but not directly.
|
||||
|
||||
### If the signal is conversational, ambiguous, or historical
|
||||
|
||||
It stays in the evidence lane:
|
||||
|
||||
- Discord
|
||||
- Discrawl archive
|
||||
- optional screener artifact
|
||||
- optional candidate queue
|
||||
|
||||
It does not become trusted project_state.
|
||||
|
||||
### If the signal is a stable personal or episodic fact
|
||||
|
||||
It may be promoted to AtoCore memory after review.
|
||||
|
||||
Examples:
|
||||
|
||||
- "Antoine prefers concise operator summaries."
|
||||
- "We decided in discussion to keep AtoCore additive."
|
||||
|
||||
These belong in reviewed memory, not in project_state.
|
||||
|
||||
### If the signal expresses a structured engineering fact
|
||||
|
||||
It may become an entity candidate and later an active entity.
|
||||
|
||||
Examples:
|
||||
|
||||
- a requirement
|
||||
- a decision
|
||||
- a constraint
|
||||
|
||||
Again, not directly from raw chat. The chat is evidence for the candidate.
|
||||
|
||||
### If the signal is the current trusted answer
|
||||
|
||||
It still should not jump directly from Discord into project_state.
|
||||
Instead, a human should explicitly curate it into project_state after checking it against the right canonical home.
|
||||
|
||||
That canonical home may be:
|
||||
|
||||
- PKM for prose and project notes
|
||||
- repo for code and design docs
|
||||
- KB tools for structured engineering facts
|
||||
- active entity if the engineering layer is the canonical home
|
||||
|
||||
## Approval boundaries
|
||||
|
||||
### Reads
|
||||
|
||||
The following may be invoked automatically when useful:
|
||||
|
||||
- `health`
|
||||
- `projects`
|
||||
- `detect-project`
|
||||
- `auto-context`
|
||||
- `query`
|
||||
- `project-state` read
|
||||
- Discrawl retrieval
|
||||
|
||||
These are additive and fail-open.
|
||||
|
||||
### Mutations requiring explicit human approval
|
||||
|
||||
The following are operator actions, not conversational automation:
|
||||
|
||||
- `register-project`
|
||||
- `update-project`
|
||||
- `refresh-project`
|
||||
- `ingest-sources`
|
||||
- `project-state-set`
|
||||
- `project-state-invalidate`
|
||||
- `capture` when used as a durable write outside conservative logging policy
|
||||
- `extract` with persistence
|
||||
- `promote`
|
||||
- `reject`
|
||||
- future entity promotion or rejection
|
||||
|
||||
For Discord-originated paths, approval must satisfy the explicit approval rule above.
|
||||
|
||||
## Shared operator client rule
|
||||
|
||||
The preferred V1 architecture is:
|
||||
|
||||
- AtoCore HTTP API as system interface
|
||||
- shared operator client as reusable mutating surface
|
||||
- OpenClaw as a thin frontend and operator around that client
|
||||
|
||||
That avoids duplicating:
|
||||
|
||||
- project detection logic
|
||||
- request logic
|
||||
- failure handling
|
||||
- mutation surface behavior
|
||||
- approval wrappers
|
||||
|
||||
OpenClaw should keep its own high-level operating instructions, but it should not keep growing a parallel AtoCore mutation implementation.
|
||||
|
||||
## V1 boundary summary
|
||||
|
||||
### Allowed automatic behavior
|
||||
|
||||
- read-only retrieval
|
||||
- context build
|
||||
- Discrawl recall
|
||||
- evidence collection
|
||||
- nightly screening into reviewable output
|
||||
- fail-open fallback when AtoCore is unavailable
|
||||
|
||||
### Allowed only after explicit human review or approval
|
||||
|
||||
- candidate persistence from evidence
|
||||
- candidate promotion or rejection
|
||||
- project refresh or ingestion
|
||||
- registry mutation
|
||||
- trusted project_state writes
|
||||
|
||||
### Not allowed as automatic behavior
|
||||
|
||||
- direct Discord -> project_state writes
|
||||
- direct Discord -> register / update / refresh / ingest / promote / reject
|
||||
- hidden mutation inside the screener
|
||||
- treating PKM as the main operator-instruction layer for AtoCore behavior
|
||||
|
||||
## Deferred from V1
|
||||
|
||||
Screenpipe is deferred.
|
||||
It is not an active input lane in V1 and it must not become a runtime, skill, or policy dependency in V1.
|
||||
If it is revisited later, it must be treated as a separate future design decision, not as an implicit V1 extension.
|
||||
|
||||
## Bottom line
|
||||
|
||||
The safe V1 architecture is not "everything can write into AtoCore."
|
||||
It is a layered system where:
|
||||
|
||||
- evidence comes in broadly
|
||||
- trust rises slowly
|
||||
- canonical homes stay singular
|
||||
- OpenClaw remains the operator
|
||||
- AtoCore remains the additive machine-memory and trusted-state layer
|
||||
- the shared operator client becomes the one reusable write-capable surface
|
||||
Reference in New Issue
Block a user