Skip to content

INTEGRATION.md

Latest commit

 

History

History
215 lines (142 loc) · 4.79 KB

INTEGRATION.md

File metadata and controls

215 lines (142 loc) · 4.79 KB
Raw

Integration Guide

This document explains how to integrate s3mem-harness into an external agent runtime such as OpenClaw.

Recommended Boundary

s3mem-harness should sit between:

  • the agent runtime that produces step logs
  • the downstream planner / answerer / policy model

Recommended flow:

  1. The runtime emits step logs.
  2. The adapter normalizes them into structured trajectory steps.
  3. S3MemHarness serializes them into episodic memories.
  4. At answer time, S3MemHarness.query(...) returns a compact evidence bundle.
  5. The downstream LLM or planner consumes only this bundle instead of the full trajectory.

This keeps the integration simple and preserves the main value of S3Mem:

  • structured write
  • anchor-sensitive retrieval
  • compact evidence routing

Integration Patterns

Pattern 1: Offline replay

Use this if you already have full trajectories on disk.

from s3mem_harness import S3MemHarness

harness = S3MemHarness()
harness.ingest_trajectory(steps, adapter="openclaw", episode_id="episode_001")
result = harness.query(question, mode="s3mem", top_k=24, token_budget=768)

Best for:

  • batch evaluation
  • log replay
  • retrospective analysis

Pattern 2: Online append

Use this when the agent is still running and you want memory to grow incrementally.

from s3mem_harness import S3MemHarness

harness = S3MemHarness()

for raw_step in stream_of_agent_steps:
    harness.ingest_trajectory([raw_step], adapter="openclaw", episode_id="episode_live", append=True)

# later
result = harness.query(question, mode="s3mem", top_k=24, token_budget=768)

Best for:

  • long-running agents
  • continual memory accumulation
  • answer-on-demand systems

Pattern 3: Memory index + downstream answerer

Use this when the agent runtime and answer-time stack are separated.

from s3mem_harness import S3MemHarness

harness = S3MemHarness()
harness.ingest_trajectory(steps, adapter="openclaw", episode_id="episode_001")
harness.save_jsonl("memory.jsonl")

other = S3MemHarness()
other.load_jsonl("memory.jsonl")
result = other.query(question)

Best for:

  • multi-process pipelines
  • serving systems
  • caching memory separately from the agent loop

Suggested Downstream Prompt Contract

The harness is designed to feed a downstream model with a compact, structured evidence package.

Suggested prompt skeleton:

You are answering a question about an agent trajectory.

Question:
{question}

Selected evidence steps:
{selected_steps}

Compressed evidence:
{compressed_text}

Support objects:
{support_objects}

Support relations:
{support_relations}

Evidence chain:
{evidence_chain}

Answer using only the evidence above. If evidence is insufficient, say so.

Choosing Modes

mode="s3mem"

Use this for the main plugin behavior.

It enables:

  • structured memory text
  • reranking
  • seed/anchor-aware retrieval
  • compact evidence packing

mode="graph_no_reader"

Use this if you want structured memory text but a weaker evidence harness.

Best for:

  • ablation
  • integration comparison

mode="vanilla_rag"

Use this as a plain summary-based baseline.

Best for:

  • control comparisons
  • debugging

Metadata-Aware Questions

The harness works best when the caller can provide structured question metadata.

Example:

{
  "question": "What did the agent do one step after obtaining alarmclock 3?",
  "metadata": {
    "answer_type": "action_after_gain_item",
    "item": "alarmclock 3",
    "occurrence": "first",
    "delta": 1
  }
}

If metadata is unavailable, the harness still runs, but retrieval is more generic.

OpenClaw-Specific Advice

For OpenClaw-like systems, the cleanest integration point is usually:

  • after each environment step is logged
  • before the final answerer or planner is called

Recommended minimum fields per step:

  • step
  • observation
  • action
  • info.location
  • info.inventory
  • info.objects

Recommended optional fields:

  • info.event
  • info.gained_items
  • info.relations
  • info.reward

Example Files

This repository includes:

  • examples/openclaw_trajectory.json
    • small synthetic example
  • examples/openclaw_real_trace_excerpt.json
    • real OpenClaw-compatible excerpt derived from an ALFWorld expert rollout
  • examples/openclaw_integration_demo.py
    • end-to-end integration demo

Practical Notes

  • Use append=True when maintaining one long-running memory store.
  • Use save_jsonl() to persist memory across processes.
  • Keep token_budget small for latency-sensitive systems.
  • Increase top_k only if recall is the bottleneck.
  • Prefer s3mem mode unless you are explicitly running a baseline.

Public Compatibility Claim

This plugin is not tied to a single benchmark. It is designed to be embedded into any step-structured agent runtime that can expose observations, actions, and optional state metadata.