MemCastle¶

Local-first, always-on memory server for AI coding agents over MCP/HTTP.

Running several AI coding agents side by side usually means each one gets its own, disconnected memory — or none at all. MemCastle is a single daemon per palace (the memory store that one or more of your projects share) that all of them talk to over MCP or HTTP, so a mining run, a search or a saved decision from one agent is immediately visible to every other agent and to the CLI. Everything lives in one SurrealDB store, embedded by default, so there is no external service to run.

flowchart LR
    A[OpenCode] & B[Claude Code] & C[Other MCP clients] -->|MCP| D
    CLI[memcastle CLI] -->|REST| D
    D[memcastle daemon] --> E[(Palace: SurrealDB)]

Get started¶

1. Install MemCastle.
2. Follow the Quickstart: start the daemon, store and search your first memories.
3. Connect an MCP client such as OpenCode or Claude Code.

Integrations¶

• Agent integrations: install, update and remove the Pi, OpenCode, Claude Code and Codex integrations, from a package or a checkout.
• Pi, OpenCode, Claude Code and Codex: what each installs, its settings and troubleshooting.
• Integration contract: what an agent integration must do, whatever the agent.

Guides¶

• Running the daemon: start, stop, supervise and check it.
• Authentication: require a bearer token from every client.
• Memory modes: make a session read-only, or turn memory off for it.
• Project configuration: scope a project's memory to a wing and room with a file in the repository.
• Agent skills: the shared instructions an integration loads for the agent.
• Mining sources: fill the palace from files, agent histories and other origins.
• Deduplication: how an exact copy or a near-duplicate memory is handled.
• Writing a mining source and Publishing and installing sources: make, distribute and install a source.
• Storage and data: where data lives, what is in it, how to back it up.
• Database access: open the daemon's database to SurrealDB Studio.
• Migrations and upgrades: how a palace is kept up to date across releases.
• Troubleshooting: diagnostic codes and what to do about them.

Reference¶

• Configuration: paths, the config file, environment variables, flags and precedence.
• CLI: every command and flag.
• MCP tools and REST API: the interfaces agents and scripts use.

Project¶

• Architecture: how MemCastle is built and why.
• Development: building, testing and the local workflow.
• Retrieval evaluation: measuring retrieval quality and latency, and comparing changes.
• Architecture Decisions: the reasoning behind the choices that shaped it.
• Contributing: commits, releases and pull requests.