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

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

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

- 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