> ## Documentation Index > Fetch the complete documentation index at: https://docs.xynthis.com/llms.txt > Use this file to discover all available pages before exploring further. # Architecture > The processes that make up Xynthis and how they talk to each other. Xynthis is a small set of cooperating processes around one always-on daemon. The daemon (the brain) owns your memory. Everything else is a client. ## The moving parts | Component | Binary | What it does | | ------------ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The brain | `xynthis-brain` | Always-on daemon. Owns all memory on disk, runs the consolidation and learning loops. | | BMC | (library) | The Binary Memory Core, the storage engine the brain hosts in-process: binary fact stores, a temporal knowledge graph, working memory, and an online reranker. | | The CLI | `xynthis` | Terminal agent and command surface: `xynthis chat`, `xynthis recall`, `xynthis confirm`, `xynthis serve`, and about 70 agent tools. | | The daemon | `xynthis serve` | HTTP + SSE server on port 3939. The app and any integration talk to it. | | MCP server | `xynthis-mcp` | A stdio MCP bridge for editors and MCP-capable assistants. Forwards tool calls into brain operations. | | The app | Xynthis.app | macOS menu-bar client of the daemon on :3939. macOS only. | | Model server | `xynthis-llm-serve` | Optional on-device LLM server. Listens on `XYNTHIS_LLM_PORT` (default 8080). | ``` ┌─────────────────────────────────────────┐ │ xynthis-brain (always-on daemon) │ │ hosts BMC in-process │ │ sole writer of ~/.xynthis/bmc/* │ └─────────────────┬───────────────────────┘ │ ~/.xynthis/brain.sock ┌───────────────┬───────────┴────────────┐ │ │ │ ┌───────┴──────┐ ┌──────┴────────┐ ┌───────────┴───────────┐ │ xynthis CLI │ │ xynthis-mcp │ │ xynthis serve (:3939) │ │ (terminal) │ │ (editors) │ │ HTTP + SSE │ └──────────────┘ └───────────────┘ └───────────┬───────────┘ │ HTTP ┌───────────┴───────────┐ │ Xynthis.app (macOS) │ │ + your integrations │ └───────────────────────┘ Optional: xynthis-llm-serve — on-device model server, XYNTHIS_LLM_PORT (default 8080) ``` ## 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](/concepts/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. ```bash theme={null} echo '{"op":"status"}' | nc -U ~/.xynthis/brain.sock ``` ## 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: | Route | Method | Purpose | | ---------------- | ------ | ----------------------------------------------------------------------------------- | | `/api/chat` | POST | One agent turn. Turns are serialized: one conversation at a time per serve process. | | `/api/chat/stop` | POST | Cancel the in-flight turn. Works while a chat is running. | | `/api/recall` | GET | Query memory. | | `/api/remember` | POST | Store a perception. | | `/api/status` | GET | Brain and agent status. | | `/api/events` | GET | SSE stream of agent events: tool calls, memory activity, plan steps. | 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/`: ``` ~/.xynthis/ ├── brain.sock # the brain's socket (the only memory API) ├── bmc/ # brain-owned memory stores — never edit by hand │ ├── xynthis_bks.bin # binary fact store (+ WAL) │ ├── xynthis_kg.bin # temporal knowledge graph │ ├── witness.log # append-only signed-fact log │ ├── identity.ed25519 # per-device signing key (mode 0600) │ └── ... # vectors, graph, identity, reranker, soul ├── sessions/ # CLI per-session state (not BMC) ├── lessons.json # CLI learned avoid/prefer pairs (not BMC) └── learned_actions.json # CLI cached fast-path actions (not BMC) ``` Treat `bmc/` as opaque. If you want to inspect or move memory, use the CLI and the socket operations; they are the supported surface.