Anto01
480f13a6df
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.
156 lines
5.0 KiB
Markdown
156 lines
5.0 KiB
Markdown
# 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
|
|
|
|
- Phase 0 - Foundation
|
|
- Phase 0.5 - Proof of Concept
|
|
- Phase 1 - Ingestion
|
|
|
|
### Baseline Complete
|
|
|
|
- Phase 2 - Memory Core
|
|
- Phase 3 - Retrieval
|
|
- Phase 5 - Project State
|
|
- Phase 7 - Context Builder
|
|
|
|
### Partial
|
|
|
|
- Phase 4 - Identity / Preferences
|
|
- Phase 8 - OpenClaw Integration
|
|
|
|
### Baseline Complete
|
|
|
|
- Phase 9 - Reflection (all three foundation commits landed:
|
|
A capture, B reinforcement, C candidate extraction + review queue)
|
|
|
|
### Not Yet Complete In The Intended Sense
|
|
|
|
- Phase 6 - AtoDrive
|
|
- Phase 10 - Write-back
|
|
- Phase 11 - Multi-model
|
|
- Phase 12 - Evaluation
|
|
- Phase 13 - Hardening
|
|
|
|
### 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)
|
|
|
|
## 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
|
|
- first organic routing layer in OpenClaw via:
|
|
- `detect-project`
|
|
- `auto-context`
|
|
|
|
## Now
|
|
|
|
These are the current practical priorities.
|
|
|
|
1. Finish practical OpenClaw integration
|
|
- make the helper lifecycle feel natural in daily use
|
|
- use the new organic routing layer for project-knowledge questions
|
|
- 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:
|
|
|
|
- after the current ingestion, retrieval, registry, OpenClaw helper, organic
|
|
routing, and backup baseline feels boring and dependable
|
|
|
|
Until then, the architecture docs should shape decisions, not force premature
|
|
schema work.
|