# AGENTS.md

## Session protocol (read first, every session)

**Before doing anything else, read `DEV-LEDGER.md` at the repo root.** It is the one-file source of truth for "what is currently true" — live SHA, active plan, open review findings, recent decisions. The narrative docs under `docs/` may lag; the ledger does not.

**Before ending a session, append a Session Log line to `DEV-LEDGER.md`** with what you did and which commit range it covers, and bump the Orientation section if anything there changed.

This rule applies equally to Claude, Codex, and any future agent working in this repo.

## 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