ATOCore/AGENTS.md

AGENTS.md

Project role

This repository is AtoCore, the runtime and machine-memory layer of the Ato ecosystem.

Ecosystem definitions

• AtoCore = app/runtime/API/ingestion/retrieval/context builder/machine DB logic
• AtoMind = future intelligence layer for promotion, reflection, conflict handling, trust decisions
• AtoVault = human-readable memory source, intended for Obsidian
• AtoDrive = trusted operational project source, higher trust than general vault notes

Storage principles

• Human-readable source layers and machine operational storage must remain separate
• AtoVault is not the live vector database location
• AtoDrive is not the live vector database location
• Machine operational storage includes SQLite, vector store, indexes, embeddings, and runtime metadata
• The machine DB is derived operational state, not the primary human source of truth

Deployment principles

• Dalidou is the canonical host for AtoCore service and machine database
• OpenClaw on the T420 should consume AtoCore over API/network/Tailscale
• Do not design around Syncthing for the live SQLite/vector DB
• Prefer one canonical running service over multi-node live DB replication

Coding guidance

• Keep path handling explicit and configurable via environment variables
• Do not hard-code machine-specific absolute paths
• Keep implementation small, testable, and reversible
• Preserve current working behavior unless a change is necessary
• Add or update tests when changing config, storage, or path logic

Change policy

Before large refactors:

1. explain the architectural reason
2. propose the smallest safe batch
3. implement incrementally
4. summarize changed files and migration impact