ATOCore/docs/source-refresh-model.md

AtoCore Source Refresh Model

Purpose

This document explains how human-authored project material should flow into the Dalidou-hosted AtoCore machine store.

It exists to make one distinction explicit:

• source markdown is not the same thing as the machine-memory layer
• source refresh is how changes in PKM or repos become visible to AtoCore

Current Model

Today, the flow is:

1. human-authoritative project material exists in PKM, AtoDrive, and repos
2. selected high-value files are staged into Dalidou source paths
3. AtoCore ingests those source files
4. AtoCore stores the processed representation in:
   • document records
   • chunks
   • vectors
   • project memory
   • trusted project state
5. retrieval and context assembly use the machine store, not the staged folder

Why This Feels Redundant

The staged source files can look almost identical to the original PKM notes or repo docs because they are still source material.

That is expected.

The staged source area exists because the canonical AtoCore instance on Dalidou needs a server-visible path to ingest from.

What Happens When A Project Source Changes

If you edit a note in PKM or a doc in a repo:

• the original source changes immediately
• the staged Dalidou copy does not change automatically
• the AtoCore machine store also does not change automatically

To refresh AtoCore:

1. select the updated project source set
2. copy or mirror the new version into the Dalidou source area
3. run ingestion again
4. verify that retrieval and context reflect the new material

Current Intentional Limits

The current active-project ingestion strategy is selective.

That means:

• not every note from a project is staged
• not every repo file is staged
• the goal is to start with high-value anchor docs
• broader ingestion comes later if needed

This is why the staged source area for a project may look partial or uneven at this stage.

Long-Run Target

The long-run workflow should become much more natural:

• each project has a registered source map
  • PKM root
  • AtoDrive root
  • repo root
  • preferred docs
  • excluded noisy paths
• a command like refresh p06-polisher resolves the right sources
• AtoCore refreshes the machine representation cleanly
• OpenClaw consumes the improved context over API

Current Foundation

The first concrete foundation for this now exists in AtoCore:

• a project registry file records known project ids, aliases, and ingest roots
• the API can list those registered projects
• the API can return a registration template for new projects
• the API can preview a proposed registration before writing it
• the API can persist an approved registration to the registry
• the API can refresh a single registered project from its configured roots

This is not full source automation yet, but it gives the refresh model a real home in the system.

Healthy Mental Model

Use this distinction:

• PKM / AtoDrive / repos = human-authoritative sources
• staged Dalidou markdown = server-visible ingestion inputs
• AtoCore DB/vector state = compiled machine context layer

That separation is intentional and healthy.