Durable Events

Durable event controller

The local event controller is mnemo's write authority. Agent hooks, plugins, native extensions and MCP clients publish events or send commands; none of them opens SQLite. The controller embeds NATS JetStream, consumes events, and applies each effect through a SQLite transaction. This gives supported agents one durable lifecycle and memory contract rather than separate write paths.

agent hooks / extensions       MCP tools and CLI readers
          |                            |
          +---- JetStream events -------+---- local request/reply or durable commands
                                       |
                              mnemo controller serve
                                       |
                               SQLite + FTS5

Lifecycle

mnemo setup refresh --agent=all creates ~/.mnemo/config.toml with an [events].port setting and registers a singleton per-user controller service. It listens only on 127.0.0.1; JetStream data lives in ~/.mnemo/events/. macOS uses launchd, Linux systemd user services, and Windows Task Scheduler. The controller starts at login and is restarted by the service manager after failure. An MCP process checks controller health but does not start a second controller.

If the controller is unavailable, publication and MCP startup fail explicitly. There is no direct-SQLite or in-memory write fallback. See Troubleshooting for recovery.

Events and commands

Publishers send agent, native execution ID, project ID from .mnemo, directory, event type and JSON payload. The Go controller derives the opaque canonical execution key. The supported event types are:

Event	Effect
execution.started	Create or bind a controller-owned session
execution.closed	Close the bound session
session.compacted	Record compaction for that session
agent.tool_result	Record a tool-use observation
workspace.file_changed	Record a file-change observation
git.commit_created	Record a decision observation

Hooks and extensions can publish with the non-writing CLI surface:

mnemo events publish --project "$PROJECT_ID" --directory "$PWD" \
  --agent pi --native-id "$NATIVE_EXECUTION_ID" \
  --type execution.started --payload "{\"directory\":\"$PWD\"}"

This is an integration API, not a manual session command. The controller acknowledges an event only after recording its idempotency key and effect in one transaction. Unbound or failed events remain available for retry. MCP reads use local request/reply; mutations enter the durable command stream and receive a reply after the transaction is committed. Redelivery returns the stored result without applying a second write.

Pi's native tools use mnemo events invoke with its native session ID. Other agents' MCP calls are bound through their documented metadata, environment, or hook-written side channel. A missing native ID is an error. See Agent Integrations for carriers and Storage and Migrations for the database.