Skip to main content
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

ComponentBinaryWhat it does
The brainxynthis-brainAlways-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 CLIxynthisTerminal agent and command surface: xynthis chat, xynthis recall, xynthis confirm, xynthis serve, and about 70 agent tools.
The daemonxynthis serveHTTP + SSE server on port 3939. The app and any integration talk to it.
MCP serverxynthis-mcpA stdio MCP bridge for editors and MCP-capable assistants. Forwards tool calls into brain operations.
The appXynthis.appmacOS menu-bar client of the daemon on :3939. macOS only.
Model serverxynthis-llm-serveOptional 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. 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. 
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:
RouteMethodPurpose
/api/chatPOSTOne agent turn. Turns are serialized: one conversation at a time per serve process.
/api/chat/stopPOSTCancel the in-flight turn. Works while a chat is running.
/api/recallGETQuery memory.
/api/rememberPOSTStore a perception.
/api/statusGETBrain and agent status.
/api/eventsGETSSE 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.