The moving parts
The brain
The brain is the one process that never stops. The installer (curl -sSfL https://xynthis.com/install.sh | bash) registers it as a launchd agent on macOS or a systemd user unit on Linux, so it starts at login and restarts if it dies.
At boot it opens every memory store under ~/.xynthis/bmc/ and holds them open for the life of the process. It then runs three loops: a cognitive tick that drains incoming perceptions into memory, a socket server that answers client requests, and a background learner that trains the recall reranker. Consolidation (the dream cycle) and reflection run on top of these; see Learning.
Clients reach the brain at ~/.xynthis/brain.sock: a Unix domain socket on macOS and Linux, a named pipe on Windows. The protocol is newline-delimited JSON: one request line in, exactly one reply line out, then the connection closes. Around 40 operations cover perception, recall, the knowledge graph, corpus management, confirmation, and consolidation. Set XYNTHIS_BRAIN_SOCKET to move the socket.
The single-writer rule
Only the brain writes to~/.xynthis/bmc/*. The CLI, the MCP server, the daemon, and the app never touch those files: every read and write goes through the brain socket, and the brain serializes them.
This is not just a convention. Each store takes an exclusive lock file on open, so a second process that tries to open a store for writing fails immediately instead of corrupting anything. The practical guarantee: you can run the CLI, the app, an editor MCP session, and a dozen scripts against the same brain at once, and your memory stays consistent. There is no scenario where two clients race each other into a corrupt store.
The CLI keeps its own per-session state (~/.xynthis/sessions/, ~/.xynthis/lessons.json, ~/.xynthis/learned_actions.json) directly on disk. Those files are agent bookkeeping, not memory; they are outside BMC and outside the rule.
The HTTP daemon
xynthis serve runs an HTTP server on port 3939. It is how anything that speaks HTTP (the app, a script, a webhook handler) reaches the agent and the brain without linking Rust code.
The main routes:
The app is a pure client of this surface. On Windows there is no app; the CLI and the daemon are the interface.
The MCP server
xynthis-mcp speaks MCP over stdio, so editors and MCP-capable assistants can use Xynthis memory as tools: recall, remember, brief, kg_query, confirm, and the rest. Each tool call becomes a brain socket operation. Nothing in the MCP server holds state of its own; it is a bridge.
The on-device model server
xynthis-llm-serve is optional. It serves a local model over HTTP on XYNTHIS_LLM_PORT (default 8080, bind address via XYNTHIS_LLM_BIND) and trains adapters in the background. Nothing else in the system requires it; the agent works with any configured provider. If you want inference that never leaves the machine, this is the piece that provides it.
On disk
Everything lives under~/.xynthis/:
bmc/ as opaque. If you want to inspect or move memory, use the CLI and the socket operations; they are the supported surface.