ATOCore/docs/openclaw-integration-contract.md

# OpenClaw Integration Contract

## Purpose

This document defines the first safe integration contract between OpenClaw and
AtoCore.

The goal is to let OpenClaw consume AtoCore as an external context service
without degrading OpenClaw's existing baseline behavior.

## Current Implemented State

The first safe integration foundation now exists on the T420 workspace:

- OpenClaw's own memory system is unchanged
- a local read-only helper skill exists at:
  - `/home/papa/clawd/skills/atocore-context/`
- the helper currently talks to the canonical Dalidou instance
- the helper has verified:
  - `health`
  - `project-state`
  - `query`
  - `detect-project`
  - `auto-context`
  - fail-open fallback when AtoCore is unavailable

This means the network and workflow foundation is working, and the first
organic routing layer now exists, even though deeper autonomous integration
into OpenClaw runtime behavior is still deferred.

## Integration Principles

- OpenClaw remains the runtime and orchestration layer
- AtoCore remains the context enrichment layer
- AtoCore is optional at runtime
- if AtoCore is unavailable, OpenClaw must continue operating normally
- initial integration is read-only
- OpenClaw should not automatically write memories, project state, or ingestion
  updates during the first integration batch

## First Safe Responsibilities

OpenClaw may use AtoCore for:

- health and readiness checks
- context building for contextual prompts
- retrieval/query support
- project-state lookup when a project is detected
- automatic project-context augmentation for project-knowledge questions

OpenClaw should not yet use AtoCore for:

- automatic memory write-back
- automatic reflection
- conflict resolution decisions
- replacing OpenClaw's own memory system

## First API Surface

OpenClaw should treat these as the initial contract:

- `GET /health`
  - check service readiness
- `GET /sources`
  - inspect source registration state
- `POST /context/build`
  - ask AtoCore for a budgeted context pack
- `POST /query`
  - use retrieval when useful

Additional project-state inspection can be added if needed, but the first
integration should stay small and resilient.

## Current Helper Surface

The current helper script exposes:

- `health`
- `sources`
- `stats`
- `projects`
- `project-template`
- `detect-project <prompt>`
- `auto-context <prompt> [budget] [project]`
- `debug-context`
- `propose-project ...`
- `register-project ...`
- `update-project ...`
- `refresh-project <project>`
- `project-state <project>`
- `query <prompt> [top_k]`
- `context-build <prompt> [project] [budget]`
- `ingest-sources`

This means OpenClaw can now use the full practical registry lifecycle for known
projects without dropping down to raw API calls.

## Failure Behavior

OpenClaw must treat AtoCore as additive.

If AtoCore times out, returns an error, or is unavailable:

- OpenClaw should continue with its own normal baseline behavior
- no hard dependency should block the user's run
- no partially written AtoCore state should be assumed

## Suggested OpenClaw Configuration

OpenClaw should eventually expose configuration like:

- `ATOCORE_ENABLED`
- `ATOCORE_BASE_URL`
- `ATOCORE_TIMEOUT_MS`
- `ATOCORE_FAIL_OPEN`

Recommended first behavior:

- enabled only when configured
- low timeout
- fail open by default
- no writeback enabled

## Suggested Usage Pattern

1. OpenClaw receives a user request
2. If the prompt looks like project knowledge, OpenClaw should try:
   - `auto-context "<prompt>" 3000`
   - optionally `debug-context` immediately after if a human wants to inspect
     the exact AtoCore supplement
3. If the prompt is clearly asking for trusted current truth, OpenClaw should
   prefer:
   - `project-state <project>`
4. If the user explicitly asked for source refresh or ingestion, OpenClaw
   should use:
   - `refresh-project <id>`
5. If AtoCore returns usable context, OpenClaw includes it
6. If AtoCore fails, returns `no_project_match`, or is unavailable, OpenClaw
   proceeds normally

## Deferred Work

- deeper automatic runtime wiring inside OpenClaw itself
- memory promotion rules
- identity and preference write flows
- reflection loop
- automatic ingestion requests from OpenClaw
- write-back policy
- conflict-resolution integration

## Precondition Before Wider Ingestion

Before bulk ingestion of projects or ecosystem notes:

- the AtoCore service should be reachable from the T420
- the OpenClaw failure fallback path should be confirmed
- the initial contract should be documented and stable