# 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