Extend the workflow
Choose the layer you need to change, then use its repository tutorial for the implementation. The guides include working examples, source files, and verification steps.
Choose an extension point
Agent harness
Your agent loop needs memory placement, tool dispatch, or lifecycle wiring.
Memory system
A new product exposes tools, MCP, skills, hooks, or a memory proxy.
Benchmark
A new task collection needs loading, ordering, environments, or scoring.
A sequence is an ordered group of tasks that can share memory. Writable state is isolated between sequences; a read-only integration can share a fixed corpus. The shared bridge handles memory lifecycle and ordering. Task grading belongs to the benchmark.
First complete workspace setup. The offline lifecycle example runs two tasks with a fake provider and needs no model keys.
Add an agent harness
A harness runs the agent’s task input, model requests, tools, and stopping logic. Choose who controls memory execution:
- Your loop controls memory: use
shared_bridge.Session. Map task boundaries, reads, directed actions, exposure receipts, and closure to the bridge lifecycle. - A native plugin or service controls memory: preserve that loop. Report observed operations through
shared_bridge.observedandEpisodeAnnotator.
For the Session path, check each result and close scopes in order. A prepared delivery is not proof of consumption: use NOT_EXPOSED only when non-delivery is known, and UNKNOWN when evidence is insufficient.
The harness tutorial includes a runnable example, multi-turn call order, failure handling, and recorder wiring. It also explains how to connect application tasks outside the supplied benchmarks.
Add a memory system
Start with one host and one operation. Preserve the product’s native tool descriptions, timing, results, and storage rules.
| Native interface | Implementation path | Example |
|---|---|---|
| Search/read/write APIs | Implement a typed provider | MemGovern, mem0 |
| MCP server | Connect native tools and record operations | SimpleMem |
| Skill, CLI, plugin, or hooks | Install and observe native behavior | MemoraX, OpenViking |
| Memory proxy | Capture the request after memory insertion | TencentDB Agent Memory |
The memory-system tutorial covers package layout, a complete lane/profile example, settings, runner registration, publication checks, and isolation tests. There is no universal plugin-registration API.
Add a benchmark
| Task source | Work required |
|---|---|
| Compatible pinned Harbor Hub dataset | Select a fixed revision and an ordered task list. Qualify the environment with the existing runner. |
| Harbor suite with special setup or checks | Extend the benchmark package and its tests. |
| Different task format or evaluator | Add a loader, sequence planner, runner, evaluator, and explicit trace joins. |
Keep reference answers, hidden tests, and scoring data separate from public task input. Save task score, agent completion, memory health, and trace completeness as distinct outcomes.
The benchmark tutorial gives concrete extension points and a public/private task-splitting example. The task catalog lists ready-to-use runners and their limits.
Record evidence for MemUse
Bridge trace sinks record lifecycle events. They do not capture model traffic. MemUse needs schema-10 recorder data with explicit memory_* annotations.
- Open episode scope before model traffic, and keep agent and memory-model lanes distinct.
- Bind each delivery to its consuming call and exact placement. A bridge input hash alone does not prove what crossed the API boundary.
- Retain search results even when they were not delivered. Preserve the exposed subset and full source provenance.
- Record confirmed writes and incomplete evidence separately. Never treat an uncertain mutation as a confirmed write.
Use the annotation contract with the MemUse input requirements. Session hosts also need request-placement hooks; installing a trace sink alone is insufficient.
Verify the integration
Use offline service doubles and scripted agent traffic to check isolation, native schemas, publication, consuming-call attribution, failure handling, and credential masking. Run the affected package tests before a live sample.
Then qualify the actual integration with an authorized live run. A writable system needs at least one write and a later recall; a read-only corpus needs relevant and no-match cases. A successful task with no memory operations does not verify the integration.
Check each recording with the recorder verifier, from the memory-bridge root:
uv run --project ../extension/traj-recorder python \
../extension/traj-recorder/tests/verify_trajectory.py path/to/recorded-runReplace the path with one recorder directory. Next, follow the offline evidence check. Report skipped checks and unverified combinations in your contribution.
Develop MemUse
After installing MemUse’s Python and agent dependencies, run the relevant offline tests from mem-use:
uv run pytest tests/test_injudge.py -q
uv run pytest tests -qFor code changes, use the focused file while iterating and run the full suite before a code PR. For prose-only edits, check links, commands, and the diff. See development for the module map and checks.
Judge prompt changes need calibration. Canned responses test the contract. Use authorized real-judge runs to assess judgment quality, and report disagreements and stability.
Report bugs or questions in the relevant project: MemUse, memory-bridge, or traj-recorder. Read the bridge contribution guide or MemUse repository rules before a PR.