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
• projects
• project-template
• 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. 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