158 lines
4.4 KiB
Markdown
158 lines
4.4 KiB
Markdown
# 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
|