Nanobot Memory Adapter Design

Goal

The adapter gives Nanobot a replaceable memory-backend slot without turning Honcho, Mem0, Graphiti, and MemOS into one synthetic memory system.

Nanobot agent loop
  -> MemoryAdapter contract
  -> backend-native client or API

Principles

1. Nanobot depends on the adapter contract, not backend SDK objects.
2. The adapter maps scope and identifiers, constructs requests, formats retrieved context, controls lifecycle, and returns audit traces.
3. Extraction, indexing, graph updates, reranking, scheduling, and other memory algorithms remain backend-native.
4. The shared abstraction is a timestamped interaction event, not a universal MemoryItem.
5. Optional capabilities are exposed only when a backend really supports them.

Core Contract

The async-first contract provides setup_scope, set_mode, record_event, retrieve, format_context, reset_scope, and health. A MemoryEvent carries run, persona, agent, session, turn, timestamp, messages, scenario, context, attribute, and metadata. A RetrieveRequest also carries an explicit context budget.

Optional capability interfaces cover bulk ingestion, readiness, native mutation, provenance, feedback, and backend-native queries. They support benchmark operations and labeled ablations; they do not enlarge the normal agent loop.

Runtime and Harness Boundary

The adapter owns memory writes, retrieval, prompt-context formatting, scope isolation, health, and backend error normalization. The MemPABench harness owns simulator and probe orchestration, frozen manifests, checkpoint branching, read-only test gates, judging, and metric aggregation.

Every write and retrieval returns structured trace data: backend, scope, native operation and identifiers, latency, consistency state, token and result counts when available, timestamps, provenance, and warnings. Missing native fields remain null; the adapter never invents comparable metadata.

Conditions and Fairness

MemPABench compares whole PA memory conditions. A condition includes its write or extraction policy, storage and retrieval mechanism, and the raw PA session context available in the shared one-entry session model. These differences are part of the tested system and are traced rather than normalized away.

No-memory and ceiling providers use the same harness boundary as architecture adapters. Test probes branch from a pinned checkpoint, disable memory writes, and skip consolidation so they cannot modify source state or one another.

Backend Mapping

Backend	Native write	Native read	Isolation and distinctive semantics
Honcho	Peer-labeled session messages	Session context, representation, or search	Workspace/peer/session; asynchronous derived state
Mem0	Memory.add(..., infer=True)	Memory.search	User/agent/run filters; extracted facts and hybrid ranking
Graphiti	Timestamped episodes	Hybrid graph search	group_id; temporal facts, invalidation, and provenance
MemOS	Requests routed to MemCubes	search_memories	User/cube routing; native text, preference, tool, and skill memory types

The selected runtime strategy is frozen in configuration. Diagnostic endpoints that add another model call, direct database writes, adapter-side re-ranking, fake hard filters, or destructive preference replacement are excluded from the normal path.

Context Formatting

format_context produces a stable backend-labeled prompt section while preserving useful native evidence. Scores, timestamps, source identifiers, temporal fields, and memory types are retained when available. Native retrieval receives the budget first; final formatting enforces the prompt limit without replacing the backend’s own selection algorithm.

Required Validation

Each adapter must prove write and retrieve behavior, run/persona isolation, read-only probe behavior, budget propagation, scoped reset, raw diagnostic preservation, and backend-specific provenance. Asynchronous backends must expose or wait for readiness. A backend is not accepted for formal runs until its real service path, checkpoint or isolation path, and failure behavior are validated.

References

• MemPABench_GAME for condition-level comparisons.
• MemPABench_Simulator_Design for simulator and probe boundaries.
• The backend projects and pinned source versions recorded in each formal RunPlan.