mcpserver

Documentation

Overview

Package mcpserver exposes brain's memory layer as an MCP server.

This is the "memory is the platform" thesis made real: any MCP host — Claude Desktop, Claude Code, Cursor, or someone's own application — connects over stdio and can build on one local, private memory that follows the user across every tool and session. The memory lives in the user's own vault; nothing is uploaded. The same store the brain app reads is the store an external agent reads and writes, so what you tell one, the others know.

The surface is deliberately more than remember/recall. Beyond reading and writing memory, an agent can assemble everything bearing on a task, record what it is doing as it works, and commit where it stopped — so a *different* agent, in a different application, can resume the same project without the user re-explaining anything. That is the point: the AI is replaceable, the context is not.

This package is an adapter and nothing more. Argument coercion, dispatch, and rendering live here; the judgement about what belongs in a context window lives in internal/contextpack, and continuity lives in internal/session.

It speaks MCP over newline-delimited JSON-RPC 2.0 on stdio — the transport every MCP host supports.

Index

• type Server
  • func New(db *sql.DB, rt *router.Router, vault string) *Server
  • func (s *Server) Serve(in io.Reader, w io.Writer) error
• type Session

Types

type Server

type Server struct {
	DB *sql.DB
	// contains filtered or unexported fields
}

Server holds the memory store and the embedding backend it recalls against. embed may be nil — the store then works without vectors (recall falls back to salience order), which is what keeps the transport testable without a live model.

func New

func New(db *sql.DB, rt *router.Router, vault string) *Server

New builds a server over an open index. rt may be nil: a machine with no model runtime still gets every continuity tool, and retrieval falls back to lexical. That is the difference between "brain is not much use here" and "the MCP server would not start", and a host only ever shows the user the second one.

func (*Server) Serve

func (s *Server) Serve(in io.Reader, w io.Writer) error

Serve runs the request loop until stdin closes. Read errors end the loop; per-request errors become JSON-RPC error responses so the host stays healthy.

One reader, one writer, one Session, one goroutine: on stdio the connection *is* the process, so this is the whole of the concurrency story. The encoder is a local rather than a field so that stays true by construction — a second caller of Serve gets its own stream and its own session state instead of quietly sharing this one's.

type Session

type Session struct {
	*Server
	// contains filtered or unexported fields
}

Session is one client's connection to the Server: the state that belongs to a conversation rather than to the process.

Everything here used to live on Server, which was true enough while stdio was the only transport — one process served exactly one client, so process state and session state were the same thing. They are not the same thing, and the conflation was two latent bugs rather than one simplification:

• the response encoder was a field, so two clients answered concurrently would interleave frames onto one stream and corrupt both;
• the project was resolved once from the launch directory, so any client that did not share that directory would be scoped to it silently, with writes landing in the wrong project rather than failing.

Splitting them costs nothing on stdio — Serve makes one Session and the behaviour is identical — and it is the precondition for any transport where the client is not the process that started us.

The embedded *Server is deliberate: the shared, immutable half (database, vault, embedding backend) promotes through, so only the handful of methods that genuinely read session state need to say so in their receiver.