2026-04-06 13:10:11 -04:00
|
|
|
# AtoCore Master Plan Status
|
|
|
|
|
|
|
|
|
|
## Current Position
|
|
|
|
|
|
|
|
|
|
AtoCore is currently between **Phase 7** and **Phase 8**.
|
|
|
|
|
|
|
|
|
|
The platform is no longer just a proof of concept. The local engine exists, the
|
|
|
|
|
core correctness pass is complete, Dalidou hosts the canonical runtime and
|
|
|
|
|
machine database, and OpenClaw on the T420 can consume AtoCore safely in
|
|
|
|
|
read-only additive mode.
|
|
|
|
|
|
|
|
|
|
## Phase Status
|
|
|
|
|
|
|
|
|
|
### Completed
|
|
|
|
|
|
2026-04-06 14:06:54 -04:00
|
|
|
- Phase 0 - Foundation
|
|
|
|
|
- Phase 0.5 - Proof of Concept
|
|
|
|
|
- Phase 1 - Ingestion
|
2026-04-06 13:10:11 -04:00
|
|
|
|
|
|
|
|
### Baseline Complete
|
|
|
|
|
|
2026-04-06 14:06:54 -04:00
|
|
|
- Phase 2 - Memory Core
|
|
|
|
|
- Phase 3 - Retrieval
|
|
|
|
|
- Phase 5 - Project State
|
|
|
|
|
- Phase 7 - Context Builder
|
2026-04-06 13:10:11 -04:00
|
|
|
|
|
|
|
|
### Partial
|
|
|
|
|
|
2026-04-06 14:06:54 -04:00
|
|
|
- Phase 4 - Identity / Preferences
|
|
|
|
|
- Phase 8 - OpenClaw Integration
|
2026-04-06 13:10:11 -04:00
|
|
|
|
docs(arch): memory-vs-entities, promotion-rules, conflict-model
Three planning docs that answer the architectural questions the
engineering query catalog raised. Together with the catalog they
form roughly half of the pre-implementation planning sprint.
docs/architecture/memory-vs-entities.md
---------------------------------------
Resolves the central question blocking every other engineering
layer doc: is a Decision a memory or an entity?
Key decisions:
- memories stay the canonical home for identity, preference, and
episodic facts
- entities become the canonical home for project, knowledge, and
adaptation facts once the engineering layer V1 ships
- no concept lives in both layers at full fidelity; one canonical
home per concept
- a "graduation" flow lets active memories upgrade into entities
(memory stays as a frozen historical pointer, never deleted)
- one shared candidate review queue across both layers
- context builder budget gains a 15% slot for engineering entities,
slotted between identity/preference memories and retrieved chunks
- the Phase 9 memory extractor's structural cues (decision heading,
constraint heading, requirement heading) are explicitly an
intentional temporary overlap, cleanly migrated via graduation
when the entity extractor ships
docs/architecture/promotion-rules.md
------------------------------------
Defines the full Layer 0 → Layer 2 pipeline:
- four layers: L0 raw source, L1 memory candidate/active, L2 entity
candidate/active, L3 trusted project state
- three extraction triggers: on interaction capture (existing),
on ingestion wave (new, batched per wave), on explicit request
- per-rule prior confidence tuned at write time by structural
signal (echoes the retriever's high/low signal hints) and
freshness bonus
- batch cap of 50 candidates per pass to protect the reviewer
- full provenance requirements: every candidate carries rule id,
source_chunk_id, source_interaction_id, and extractor_version
- reversibility matrix for every promotion step
- explicit no-auto-promotion-in-V1 stance with the schema designed
so auto-promotion policies can be added later without migration
- the hard invariant: nothing ever moves into L3 automatically
- ingestion-wave extraction produces a report artifact under
data/extraction-reports/<wave-id>/
docs/architecture/conflict-model.md
-----------------------------------
Defines how AtoCore handles contradictory facts without violating
the "bad memory is worse than no memory" rule.
- conflict = two or more active rows claiming the same slot with
incompatible values
- per-type "slot key" tuples for both memory and entity types
- cross-layer conflict detection respects the trust hierarchy:
trusted project state > active entities > active memories
- new conflicts and conflict_members tables (schema proposal)
- detection at two latencies: synchronous at write time,
asynchronous nightly sweep
- "flag, never block" rule: writes always succeed, conflicts are
surfaced via /conflicts, /health open_conflicts_count, per-row
response bodies, and the Human Mirror's disputed marker
- resolution is always human: promote-winner + supersede-others,
or dismiss-as-not-a-real-conflict, both with audit trail
- explicitly out of scope for V1: cross-project conflicts,
temporal-overlap conflicts, tolerance-aware numeric comparisons
Also updates:
- master-plan-status.md: Phase 9 moved from "started" to "baseline
complete" now that Commits A, B, C are all landed
- master-plan-status.md: adds a "Engineering Layer Planning Sprint"
section listing the doc wave so far and the remaining docs
(tool-handoff-boundaries, human-mirror-rules,
representation-authority, engineering-v1-acceptance)
- current-state.md: Phase 9 moved from "not started" to "baseline
complete" with the A/B/C annotation
This is pure doc work. No code changes, no schema changes, no
behavior changes. Per the working rule in master-plan-status.md:
the architecture docs shape decisions, they do not force premature
schema work.
2026-04-06 21:30:35 -04:00
|
|
|
### Baseline Complete
|
feat(phase9-A): interaction capture loop foundation
Phase 9 Commit A from the agreed plan: turn AtoCore from a stateless
context enhancer into a system that records what it actually fed to an
LLM and what came back. This is the audit trail Reflection (Commit B)
and Extraction (Commit C) will be layered on top of.
The interactions table existed in the schema since the original PoC
but nothing wrote to it. This change makes it real:
Schema migration (additive only):
- response full LLM response (caller decides how much)
- memories_used JSON list of memory ids in the context pack
- chunks_used JSON list of chunk ids in the context pack
- client identifier of the calling system
(openclaw, claude-code, manual, ...)
- session_id groups multi-turn conversations
- project project name (mirrors the memory module pattern,
no FK so capture stays cheap)
- indexes on session_id, project, created_at
The created_at column is now written explicitly with a SQLite-compatible
'YYYY-MM-DD HH:MM:SS' format so the same string lives in the DB and the
returned dataclass. Without this the `since` filter on list_interactions
would silently fail because CURRENT_TIMESTAMP and isoformat use different
shapes that do not compare cleanly as strings.
New module src/atocore/interactions/:
- Interaction dataclass
- record_interaction() persists one round-trip (prompt required;
everything else optional). Refuses empty prompts.
- list_interactions() filters by project / session_id / client / since,
newest-first, hard-capped at 500
- get_interaction() fetch by id, full response + context pack
API endpoints:
- POST /interactions capture one interaction
- GET /interactions list with summaries (no full response)
- GET /interactions/{id} full record incl. response + pack
Trust model:
- Capture is read-only with respect to memories, project state, and
source chunks. Nothing here promotes anything into trusted state.
- The audit trail becomes the dataset Commit B (reinforcement) and
Commit C (extraction + review queue) will operate on.
Tests (13 new, all green):
- service: persist + roundtrip every field
- service: minimum-fields path (prompt only)
- service: empty / whitespace prompt rejected
- service: get by id returns None for missing
- service: filter by project, session, client
- service: ordering newest-first with limit
- service: since filter inclusive on cutoff (the bug the timestamp
fix above caught)
- service: limit=0 returns empty
- API: POST records and round-trips through GET /interactions/{id}
- API: empty prompt returns 400
- API: missing id returns 404
- API: list filter returns summaries (not full response bodies)
Full suite: 118 passing (was 105).
master-plan-status.md updated to move Phase 9 from "not started" to
"started" with the explicit note that Commit A is in and Commits B/C
remain.
2026-04-06 19:31:43 -04:00
|
|
|
|
docs(arch): memory-vs-entities, promotion-rules, conflict-model
Three planning docs that answer the architectural questions the
engineering query catalog raised. Together with the catalog they
form roughly half of the pre-implementation planning sprint.
docs/architecture/memory-vs-entities.md
---------------------------------------
Resolves the central question blocking every other engineering
layer doc: is a Decision a memory or an entity?
Key decisions:
- memories stay the canonical home for identity, preference, and
episodic facts
- entities become the canonical home for project, knowledge, and
adaptation facts once the engineering layer V1 ships
- no concept lives in both layers at full fidelity; one canonical
home per concept
- a "graduation" flow lets active memories upgrade into entities
(memory stays as a frozen historical pointer, never deleted)
- one shared candidate review queue across both layers
- context builder budget gains a 15% slot for engineering entities,
slotted between identity/preference memories and retrieved chunks
- the Phase 9 memory extractor's structural cues (decision heading,
constraint heading, requirement heading) are explicitly an
intentional temporary overlap, cleanly migrated via graduation
when the entity extractor ships
docs/architecture/promotion-rules.md
------------------------------------
Defines the full Layer 0 → Layer 2 pipeline:
- four layers: L0 raw source, L1 memory candidate/active, L2 entity
candidate/active, L3 trusted project state
- three extraction triggers: on interaction capture (existing),
on ingestion wave (new, batched per wave), on explicit request
- per-rule prior confidence tuned at write time by structural
signal (echoes the retriever's high/low signal hints) and
freshness bonus
- batch cap of 50 candidates per pass to protect the reviewer
- full provenance requirements: every candidate carries rule id,
source_chunk_id, source_interaction_id, and extractor_version
- reversibility matrix for every promotion step
- explicit no-auto-promotion-in-V1 stance with the schema designed
so auto-promotion policies can be added later without migration
- the hard invariant: nothing ever moves into L3 automatically
- ingestion-wave extraction produces a report artifact under
data/extraction-reports/<wave-id>/
docs/architecture/conflict-model.md
-----------------------------------
Defines how AtoCore handles contradictory facts without violating
the "bad memory is worse than no memory" rule.
- conflict = two or more active rows claiming the same slot with
incompatible values
- per-type "slot key" tuples for both memory and entity types
- cross-layer conflict detection respects the trust hierarchy:
trusted project state > active entities > active memories
- new conflicts and conflict_members tables (schema proposal)
- detection at two latencies: synchronous at write time,
asynchronous nightly sweep
- "flag, never block" rule: writes always succeed, conflicts are
surfaced via /conflicts, /health open_conflicts_count, per-row
response bodies, and the Human Mirror's disputed marker
- resolution is always human: promote-winner + supersede-others,
or dismiss-as-not-a-real-conflict, both with audit trail
- explicitly out of scope for V1: cross-project conflicts,
temporal-overlap conflicts, tolerance-aware numeric comparisons
Also updates:
- master-plan-status.md: Phase 9 moved from "started" to "baseline
complete" now that Commits A, B, C are all landed
- master-plan-status.md: adds a "Engineering Layer Planning Sprint"
section listing the doc wave so far and the remaining docs
(tool-handoff-boundaries, human-mirror-rules,
representation-authority, engineering-v1-acceptance)
- current-state.md: Phase 9 moved from "not started" to "baseline
complete" with the A/B/C annotation
This is pure doc work. No code changes, no schema changes, no
behavior changes. Per the working rule in master-plan-status.md:
the architecture docs shape decisions, they do not force premature
schema work.
2026-04-06 21:30:35 -04:00
|
|
|
- Phase 9 - Reflection (all three foundation commits landed:
|
|
|
|
|
A capture, B reinforcement, C candidate extraction + review queue)
|
feat(phase9-A): interaction capture loop foundation
Phase 9 Commit A from the agreed plan: turn AtoCore from a stateless
context enhancer into a system that records what it actually fed to an
LLM and what came back. This is the audit trail Reflection (Commit B)
and Extraction (Commit C) will be layered on top of.
The interactions table existed in the schema since the original PoC
but nothing wrote to it. This change makes it real:
Schema migration (additive only):
- response full LLM response (caller decides how much)
- memories_used JSON list of memory ids in the context pack
- chunks_used JSON list of chunk ids in the context pack
- client identifier of the calling system
(openclaw, claude-code, manual, ...)
- session_id groups multi-turn conversations
- project project name (mirrors the memory module pattern,
no FK so capture stays cheap)
- indexes on session_id, project, created_at
The created_at column is now written explicitly with a SQLite-compatible
'YYYY-MM-DD HH:MM:SS' format so the same string lives in the DB and the
returned dataclass. Without this the `since` filter on list_interactions
would silently fail because CURRENT_TIMESTAMP and isoformat use different
shapes that do not compare cleanly as strings.
New module src/atocore/interactions/:
- Interaction dataclass
- record_interaction() persists one round-trip (prompt required;
everything else optional). Refuses empty prompts.
- list_interactions() filters by project / session_id / client / since,
newest-first, hard-capped at 500
- get_interaction() fetch by id, full response + context pack
API endpoints:
- POST /interactions capture one interaction
- GET /interactions list with summaries (no full response)
- GET /interactions/{id} full record incl. response + pack
Trust model:
- Capture is read-only with respect to memories, project state, and
source chunks. Nothing here promotes anything into trusted state.
- The audit trail becomes the dataset Commit B (reinforcement) and
Commit C (extraction + review queue) will operate on.
Tests (13 new, all green):
- service: persist + roundtrip every field
- service: minimum-fields path (prompt only)
- service: empty / whitespace prompt rejected
- service: get by id returns None for missing
- service: filter by project, session, client
- service: ordering newest-first with limit
- service: since filter inclusive on cutoff (the bug the timestamp
fix above caught)
- service: limit=0 returns empty
- API: POST records and round-trips through GET /interactions/{id}
- API: empty prompt returns 400
- API: missing id returns 404
- API: list filter returns summaries (not full response bodies)
Full suite: 118 passing (was 105).
master-plan-status.md updated to move Phase 9 from "not started" to
"started" with the explicit note that Commit A is in and Commits B/C
remain.
2026-04-06 19:31:43 -04:00
|
|
|
|
2026-04-06 13:10:11 -04:00
|
|
|
### Not Yet Complete In The Intended Sense
|
|
|
|
|
|
2026-04-06 14:06:54 -04:00
|
|
|
- Phase 6 - AtoDrive
|
|
|
|
|
- Phase 10 - Write-back
|
|
|
|
|
- Phase 11 - Multi-model
|
|
|
|
|
- Phase 12 - Evaluation
|
|
|
|
|
- Phase 13 - Hardening
|
2026-04-06 13:10:11 -04:00
|
|
|
|
docs(arch): memory-vs-entities, promotion-rules, conflict-model
Three planning docs that answer the architectural questions the
engineering query catalog raised. Together with the catalog they
form roughly half of the pre-implementation planning sprint.
docs/architecture/memory-vs-entities.md
---------------------------------------
Resolves the central question blocking every other engineering
layer doc: is a Decision a memory or an entity?
Key decisions:
- memories stay the canonical home for identity, preference, and
episodic facts
- entities become the canonical home for project, knowledge, and
adaptation facts once the engineering layer V1 ships
- no concept lives in both layers at full fidelity; one canonical
home per concept
- a "graduation" flow lets active memories upgrade into entities
(memory stays as a frozen historical pointer, never deleted)
- one shared candidate review queue across both layers
- context builder budget gains a 15% slot for engineering entities,
slotted between identity/preference memories and retrieved chunks
- the Phase 9 memory extractor's structural cues (decision heading,
constraint heading, requirement heading) are explicitly an
intentional temporary overlap, cleanly migrated via graduation
when the entity extractor ships
docs/architecture/promotion-rules.md
------------------------------------
Defines the full Layer 0 → Layer 2 pipeline:
- four layers: L0 raw source, L1 memory candidate/active, L2 entity
candidate/active, L3 trusted project state
- three extraction triggers: on interaction capture (existing),
on ingestion wave (new, batched per wave), on explicit request
- per-rule prior confidence tuned at write time by structural
signal (echoes the retriever's high/low signal hints) and
freshness bonus
- batch cap of 50 candidates per pass to protect the reviewer
- full provenance requirements: every candidate carries rule id,
source_chunk_id, source_interaction_id, and extractor_version
- reversibility matrix for every promotion step
- explicit no-auto-promotion-in-V1 stance with the schema designed
so auto-promotion policies can be added later without migration
- the hard invariant: nothing ever moves into L3 automatically
- ingestion-wave extraction produces a report artifact under
data/extraction-reports/<wave-id>/
docs/architecture/conflict-model.md
-----------------------------------
Defines how AtoCore handles contradictory facts without violating
the "bad memory is worse than no memory" rule.
- conflict = two or more active rows claiming the same slot with
incompatible values
- per-type "slot key" tuples for both memory and entity types
- cross-layer conflict detection respects the trust hierarchy:
trusted project state > active entities > active memories
- new conflicts and conflict_members tables (schema proposal)
- detection at two latencies: synchronous at write time,
asynchronous nightly sweep
- "flag, never block" rule: writes always succeed, conflicts are
surfaced via /conflicts, /health open_conflicts_count, per-row
response bodies, and the Human Mirror's disputed marker
- resolution is always human: promote-winner + supersede-others,
or dismiss-as-not-a-real-conflict, both with audit trail
- explicitly out of scope for V1: cross-project conflicts,
temporal-overlap conflicts, tolerance-aware numeric comparisons
Also updates:
- master-plan-status.md: Phase 9 moved from "started" to "baseline
complete" now that Commits A, B, C are all landed
- master-plan-status.md: adds a "Engineering Layer Planning Sprint"
section listing the doc wave so far and the remaining docs
(tool-handoff-boundaries, human-mirror-rules,
representation-authority, engineering-v1-acceptance)
- current-state.md: Phase 9 moved from "not started" to "baseline
complete" with the A/B/C annotation
This is pure doc work. No code changes, no schema changes, no
behavior changes. Per the working rule in master-plan-status.md:
the architecture docs shape decisions, they do not force premature
schema work.
2026-04-06 21:30:35 -04:00
|
|
|
### Engineering Layer Planning Sprint
|
|
|
|
|
|
|
|
|
|
The engineering layer is intentionally in planning, not implementation.
|
|
|
|
|
The architecture docs below are the current state of that planning:
|
|
|
|
|
|
|
|
|
|
- [engineering-query-catalog.md](architecture/engineering-query-catalog.md) —
|
|
|
|
|
the 20 v1-required queries the engineering layer must answer
|
|
|
|
|
- [memory-vs-entities.md](architecture/memory-vs-entities.md) —
|
|
|
|
|
canonical home split between memory and entity tables
|
|
|
|
|
- [promotion-rules.md](architecture/promotion-rules.md) —
|
|
|
|
|
Layer 0 → Layer 2 pipeline, triggers, review queue mechanics
|
|
|
|
|
- [conflict-model.md](architecture/conflict-model.md) —
|
|
|
|
|
detection, representation, and resolution of contradictory facts
|
|
|
|
|
- [engineering-knowledge-hybrid-architecture.md](architecture/engineering-knowledge-hybrid-architecture.md) —
|
|
|
|
|
the 5-layer model (from the previous planning wave)
|
|
|
|
|
- [engineering-ontology-v1.md](architecture/engineering-ontology-v1.md) —
|
|
|
|
|
the initial V1 object and relationship inventory (previous wave)
|
|
|
|
|
|
|
|
|
|
Still to draft before engineering-layer implementation begins:
|
|
|
|
|
|
|
|
|
|
- tool-handoff-boundaries.md (KB-CAD / KB-FEM read vs write)
|
|
|
|
|
- human-mirror-rules.md (templates, triggers, edit flow)
|
|
|
|
|
- representation-authority.md (PKM / KB / repo / AtoCore canonical home matrix)
|
|
|
|
|
- engineering-v1-acceptance.md (done definition)
|
|
|
|
|
|
2026-04-06 13:10:11 -04:00
|
|
|
## What Is Real Today
|
|
|
|
|
|
|
|
|
|
- canonical AtoCore runtime on Dalidou
|
|
|
|
|
- canonical machine DB and vector store on Dalidou
|
|
|
|
|
- project registry with:
|
|
|
|
|
- template
|
|
|
|
|
- proposal preview
|
|
|
|
|
- register
|
|
|
|
|
- update
|
|
|
|
|
- refresh
|
|
|
|
|
- read-only additive OpenClaw helper on the T420
|
|
|
|
|
- seeded project corpus for:
|
|
|
|
|
- `p04-gigabit`
|
|
|
|
|
- `p05-interferometer`
|
|
|
|
|
- `p06-polisher`
|
|
|
|
|
- conservative Trusted Project State for those active projects
|
|
|
|
|
- first operational backup foundation for SQLite + project registry
|
|
|
|
|
- implementation-facing architecture notes for future engineering knowledge work
|
2026-04-06 14:06:54 -04:00
|
|
|
- first organic routing layer in OpenClaw via:
|
|
|
|
|
- `detect-project`
|
|
|
|
|
- `auto-context`
|
2026-04-06 13:10:11 -04:00
|
|
|
|
|
|
|
|
## Now
|
|
|
|
|
|
|
|
|
|
These are the current practical priorities.
|
|
|
|
|
|
|
|
|
|
1. Finish practical OpenClaw integration
|
|
|
|
|
- make the helper lifecycle feel natural in daily use
|
2026-04-06 14:04:49 -04:00
|
|
|
- use the new organic routing layer for project-knowledge questions
|
2026-04-06 13:10:11 -04:00
|
|
|
- confirm fail-open behavior remains acceptable
|
|
|
|
|
- keep AtoCore clearly additive
|
|
|
|
|
2. Tighten retrieval quality
|
|
|
|
|
- reduce cross-project competition
|
|
|
|
|
- improve ranking on short or ambiguous prompts
|
|
|
|
|
- add only a few anchor docs where retrieval is still weak
|
|
|
|
|
3. Continue controlled ingestion
|
|
|
|
|
- deepen active projects selectively
|
|
|
|
|
- avoid noisy bulk corpus growth
|
|
|
|
|
4. Strengthen operational boringness
|
|
|
|
|
- backup and restore procedure
|
|
|
|
|
- Chroma rebuild / backup policy
|
|
|
|
|
- retention and restore validation
|
|
|
|
|
|
|
|
|
|
## Next
|
|
|
|
|
|
|
|
|
|
These are the next major layers after the current practical pass.
|
|
|
|
|
|
|
|
|
|
1. Clarify AtoDrive as a real operational truth layer
|
|
|
|
|
2. Mature identity / preferences handling
|
|
|
|
|
3. Improve observability for:
|
|
|
|
|
- retrieval quality
|
|
|
|
|
- context-pack inspection
|
|
|
|
|
- comparison of behavior with and without AtoCore
|
|
|
|
|
|
|
|
|
|
## Later
|
|
|
|
|
|
|
|
|
|
These are the deliberate future expansions already supported by the architecture
|
|
|
|
|
direction, but not yet ready for immediate implementation.
|
|
|
|
|
|
|
|
|
|
1. Minimal engineering knowledge layer
|
|
|
|
|
- driven by `docs/architecture/engineering-knowledge-hybrid-architecture.md`
|
|
|
|
|
- guided by `docs/architecture/engineering-ontology-v1.md`
|
|
|
|
|
2. Minimal typed objects and relationships
|
|
|
|
|
3. Evidence-linking and provenance-rich structured records
|
|
|
|
|
4. Human mirror generation from structured state
|
|
|
|
|
|
|
|
|
|
## Not Yet
|
|
|
|
|
|
|
|
|
|
These remain intentionally deferred.
|
|
|
|
|
|
|
|
|
|
- automatic write-back from OpenClaw into AtoCore
|
|
|
|
|
- automatic memory promotion
|
|
|
|
|
- reflection loop integration
|
|
|
|
|
- replacing OpenClaw's own memory system
|
|
|
|
|
- live machine-DB sync between machines
|
|
|
|
|
- full ontology / graph expansion before the current baseline is stable
|
|
|
|
|
|
|
|
|
|
## Working Rule
|
|
|
|
|
|
|
|
|
|
The next sensible implementation threshold for the engineering ontology work is:
|
|
|
|
|
|
2026-04-06 14:06:54 -04:00
|
|
|
- after the current ingestion, retrieval, registry, OpenClaw helper, organic
|
|
|
|
|
routing, and backup baseline feels boring and dependable
|
2026-04-06 13:10:11 -04:00
|
|
|
|
|
|
|
|
Until then, the architecture docs should shape decisions, not force premature
|
|
|
|
|
schema work.
|