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`
  - fail-open fallback when AtoCore is unavailable

This means the network and workflow foundation is working, even though deeper
automatic 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

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`
- `project-state <project>`
- `query <prompt> [top_k]`
- `context-build <prompt> [project] [budget]`
- `ingest-sources`

## 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. OpenClaw decides whether the request is contextual enough to query AtoCore
3. If yes, OpenClaw calls AtoCore
4. If AtoCore returns usable context, OpenClaw includes it
5. If AtoCore fails or returns nothing useful, 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