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