Integration Recipe: A Memory Sidecar for Any Go Agent Harness

This recipe assumes the harness can emit events and amend a prompt. It does not assume a particular agent framework.

1. Capture

Map user, assistant, and tool events into newline-delimited JSON. Write only the fields required for extraction and scrub credentials before persistence.

2. Extract

semantix extract --input session.jsonl --db .semantix/project.db --project demo
semantix search --query "fix the failing Go test" --db .semantix/project.db --retriever hybrid
semantix inject --query "fix the failing Go test" --db .semantix/project.db
semantix verify --session ./sessions --project demo > eval.tsv

Choose project scope for repository knowledge and user scope only for genuinely cross-project preferences. Keep the database path explicit in deployment configuration.

3. Retrieve and inject

Use hybrid as an experiment, not a default belief. Log the selected slice IDs, scores, query, and token budget. Put the marked reuse block in one predictable location so it can be removed during an A/B comparison.

4. Roll back

If the sidecar exits nonzero or times out, continue without injection. If a selected slice is wrong, record rejection and remove or downweight it. Direct result reuse should remain disabled unless dependency verification is available for that task.

5. Verify

Run go vet, go test, a fixture-to-injection smoke test, scope-negative tests, and held-out replay through semantix verify. Measure downstream task completion as well as retrieval relevance.

Limits

This recipe proves portability of the integration contract, not equal behavior in every harness. Prompt construction, event timing, permissions, and cancellation semantics remain harness-specific work.

A run from the integration boundary

On 2026-08-12 I executed the packages behind capture, retrieval, and rollback from main e93668e with Go 1.26.5 on Windows/amd64:

go test -count=1 ./kernel/event ./kernel/bm25 ./kernel/inject ./kernel/usage

Observed result:

ok  semantix/kernel/event
ok  semantix/kernel/bm25
ok  semantix/kernel/inject
ok  semantix/kernel/usage

The output shows that these repository contracts are exercised together at package level. It does not show a deployed agent saving tokens or completing more tasks. My deployment checklist would record the harness version, fixture checksum, retrieved slice IDs, task outcome, latency, and rollback result. Without that record, “framework-neutral” describes the boundary shape only.

The integration mistake I would avoid

The tempting implementation is to capture every event and inject every high-scoring slice. I would not start there. Tool streams contain partial arguments, duplicate status messages, secrets, and results that are valid only for one checkout. More memory can make the next prompt longer while making its answer worse.

For a first adapter, I would capture only the user request and completed tool result, then log the event ID before extraction. On retrieval, I would record the query, selected slice IDs, scores, and the exact marked block inserted into the prompt. A rejected slice should remain visible in the evaluation record instead of silently disappearing after a threshold change.

The failure path is part of the contract. If the database is locked, retrieval exceeds its deadline, or the marked block cannot be removed cleanly, the harness should proceed without memory and report that fallback. This makes the sidecar optional in operation, not merely optional in an architecture diagram.

My next comparison would replay a frozen session set twice: once with the marked block and once without it. The decision metric would combine task completion, incorrect reuse, prompt-token change, latency, and rollback success. Until such a comparison is published, the package tests support an integration-boundary claim, not a claim of production benefit.

Sources and limitations

• Quickstart — commands and supported release paths.
• M0 gate report — what passed, what is conditional, and what remains unverified.
• Source and tests — implementation is the final authority.