ATOCore/docs/openclaw-atocore-v1-architecture.md

# 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