mempalace/website/concepts/agent-logstream.md

Agent Logstream

MemPalace is a memory system first — but agents sharing one palace also need to coordinate: delegate work to each other, wait for replies, and hand off patches without a human relaying messages between machines. The logstream is that coordination layer (RFC 003).

It is a small append-only event log served by the same MemPalace hub that serves memory, stored next to the palace as logstream.sqlite3. It follows the same promises as everything else in MemPalace:

• Local-first — lives inside your palace directory, reachable over loopback, LAN, or tailnet exactly like the rest of the hub. No cloud queue, no Redis, no SaaS.
• Exact payloads — event bodies and artifacts are stored verbatim, byte-for-byte, with a SHA-256 for verification.
• Append-only — events are immutable. Corrections and acknowledgements are new events that reference prior ones.
• Durable before realtime — everything is recoverable after a reconnect; nothing exists only in a socket.

Events

An event is a structured coordination message with routing metadata and an optional verbatim body:

{
  "id": "evt_20260702T032443_02ce0c31acdb",
  "type": "patch.ready",
  "stream": "project/mempalace",
  "room": "patches",
  "from_agent": "windows-codex",
  "to_agent": "mac-codex",
  "correlation_id": "task_123",
  "branch": "feat/my-feature",
  "base_commit": "2668053",
  "status": "ready",
  "artifact_ids": ["art_20260702T032443_e5cb86f7aba8"],
  "body": "Search ranking patch is ready. Tests passed on Windows.",
  "created_at": "2026-07-02T03:24:43Z"
}

• stream is the broad channel — project/<name> for per-project work, or a shared channel like shared_agent_brain.
• room is the sub-channel: delegation, patches, reviews, status.
• correlation_id ties a request to its replies and acks. Generate one per task and carry it through the whole exchange.
• to_agent targets one agent, or * to broadcast. Filters on to_agent also match broadcasts.
• status is one of open, claimed, ready, applied, blocked, failed, superseded.
• seq (returned on every event) is the append-order cursor. Pass the last seen event's id as since_event_id to resume exactly where you left off.

Artifacts

An artifact is exact content attached to an event: a unified diff, a generated file, a test log, a JSON report. Artifacts are stored verbatim with sha256 and size_bytes, so the receiving agent can verify integrity before applying anything. v1 artifacts are UTF-8 text, up to 4 MiB.

The delegation loop

The canonical two-agent exchange:

Requester (agent A):

1. mempalace_event_append — type=task.request, to_agent=agent-b, correlation_id=task_123, body describing the work.
2. mempalace_event_wait — correlation_id=task_123, type=patch.ready, timeout_ms=300000.
3. mempalace_artifact_get — fetch the patch, verify the sha256.
4. Apply the patch locally, run tests. Patch application is always an explicit local decision — the logstream never applies anything for you.
5. mempalace_event_ack — status=applied (or failed with notes).

Worker (agent B):

1. mempalace_event_wait — to_agent=agent-b, type=task.request.
2. Do the work.
3. mempalace_patch_submit — stores the artifact and appends the patch.ready event in one call.

If an agent can't produce a patch, it still replies: task.reply or a blocked/failed status with verbatim notes. Silence is the only failure mode the logstream can't help with.

mempalace_event_wait is a long-poll: it blocks up to 5 minutes and returns { "timed_out": true, "events": [] } on timeout rather than erroring. Loop on it for longer waits, passing since_event_id to avoid reprocessing.

Tools and CLI

Seven MCP tools serve the logstream: mempalace_event_append, mempalace_event_list, mempalace_event_wait, mempalace_event_ack, mempalace_artifact_put, mempalace_artifact_get, and mempalace_patch_submit — see the MCP tools reference for schemas.

The same operations are available from the shell:

mempalace logstream append --type task.request --stream project/myapp \
  --room delegation --from-agent mac --to-agent windows \
  --correlation-id task_123 --body "Please fix the flaky test."

mempalace logstream wait --correlation-id task_123 --type patch.ready \
  --timeout-ms 300000 --json

mempalace artifact get art_... | git apply --3way

--json makes every command scriptable; wait exits 2 on timeout so shell loops can retry.

For push-based consumers (dashboards, live viewers), the hub also serves the stream over Server-Sent Events at GET /logstream/stream — same filters, same JSON envelope, since_event_id resume — see Shared Brain.

Coordination vs. memory

The logstream complements the palace; it does not replace it:

	Palace (drawers)	Logstream (events)
Purpose	Long-term recall	Active coordination
Access	Semantic search	Structured filters + long-poll
Lifetime	Forever	Forever (append-only)
Content	Anything worth remembering	Work packets, replies, patches

Durable outcomes still belong in the palace: when a delegated task concludes, file the decision and outcome as a drawer so it is searchable later. The event trail records how the work moved between agents; the drawer records what was learned.

The logstream is deliberately independent of the vector index — it opens no Chroma handles, so coordination keeps working even while the palace index is being mined, repaired, or rebuilt.