How This Blog Connects to Alexandria

A specialist call from my blog’s repo carries close to 40,000 characters of blog context, on the order of 10,000 tokens, before the task even starts. This page traces how that context gets there and where it goes afterwards. It’s the companion to I Built Alexandria for My AI Agents, whose integration section describes an earlier setup that this page replaces.

The shape

1. From repo to MCP server. At startup the server walks up from the working directory to .alexandria/project.json and reads the files it declares.
2. From MCP server to service. An alexandria_run_agent call sends the project name, the project context, the task, and any attached files. alexandria_ask sends the same without files.
3. From service back to MCP server. One assembled prompt comes back, with agent instructions, verified facts, and relevant learnings.
4. From MCP server to your model. In delegate mode, your coding tool’s own model writes the answer. Execute mode calls a model provider directly and returns the finished output.

alexandria_doctor shows which mode you’re in, and the server can be pinned to delegate.

The folder

.alexandria/
├── project.json            read: the only required file
├── voice.json              read: declared in configs
├── voice-exemplars.md      read: declared in configs
├── brand.json              read: declared in configs
├── context/*.md            read: auto_load, in priority order
├── visual-style-library/   ignored
└── voice-violations.log    ignored, gitignored

The MCP server loads only declared files, and each one loads in full with no size budget. That’s where my blog’s context comes from. Two exceptions apply. A project.json with no configs block falls back to brand.json, voice.json and voice-exemplars.md when they exist. The npm CLI caps project context at context.max_tokens, 4,000 tokens by default, and drops the blocks that don’t fit. Without the folder, the tools run without project context. The server reads the folder only at startup, so restart the coding tool session after editing it.

project.json, field by field

A trimmed example:

{
  "name": "my-blog",
  "configs": {
    "voice": "voice.json",
    "voice-exemplars": "voice-exemplars.md",
    "brand": "brand.json"
  },
  "context": {
    "auto_load": ["context/*.md"],
    "priority": ["context/content-strategy.md"]
  },
  "privacy": { "learnings": "project" }
}

What version 4.9.0 of the MCP server reads:

• name labels the project on every call.
• configs maps a role to a file in .alexandria/, and custom roles work too.
• context.auto_load supports exactly "context/*.md", and context.priority sets which files load first.
• privacy.learnings controls which learnings get uploaded.

The spec also lists type, description, agents.*, privacy.context_mode, privacy.redact_patterns, privacy.telemetry and links, but no current client reads them. context.max_tokens matters only to the npm CLI. Since redact_patterns redacts nothing, keep secrets out of the folder.

How voice and brand become prompt text

What does the model actually see? JSON configs are flattened into key: value lines and Markdown goes in verbatim, each under a ## Role heading. My blog’s "em_dash_max_per_article": 0 gate reaches the model as a plain directive under ## Voice.

Project context sits ahead of the agent’s own instructions, so whatever the folder declares steers every agent. Treat a cloned repo’s .alexandria/ like code you’re about to run, and read it before you start a coding session there.

Nothing filters configs per agent, which means a design agent reads the voice spec too. A declared brand.json also sets the default image style for alexandria_generate_image.

Calling specialists from the editor

In delegate mode, alexandria_ask matches a task to an agent locally and returns that agent’s prompt for your model to answer, or the catalog when no match is confident. alexandria_run_agent calls a named agent with a task and optional files. My blog routes by stage:

The worked example is my blog’s /voice-check command, which calls alexandria_run_agent with voice-analyst, a short brief, and the article body. For setup trouble, alexandria_doctor checks mode, auth, connectivity, .alexandria/ detection, and routing.

What flows back

Retrieval is automatic: the service adds a few learnings similar to the task, and project-scoped ones are used only for calls that carry the same project name.

Execute mode captures each run as a learning under the policy below. Delegate mode stores no learning until you call alexandria_learn, though the service keeps a session record of every task it receives, attached files included. alexandria_outcome records whether a task worked, and alexandria_context, new in 4.9.0, manages verified facts for the project.

In MCP server 4.9.0, privacy.learnings takes three values:

• project, the default: only runs for the same project see its learnings.
• shared: every project in the account can retrieve them.
• local: nothing uploads. Unknown values and unparseable files land here too.

Older builds handled the key differently, so check which version your coding tool runs, and set the key explicitly rather than relying on a default.

What stays where

So what leaves your machine? A call that reaches an agent sends the project context and the task to the service, plus any attached files on run_agent. A delegate-mode ask that finds no confident match returns the catalog and sends nothing. privacy.learnings covers learnings only, so declaring fewer files is the one way to send less.

Access

Alexandria is in private beta with no public signup, and its API isn’t documented here.

Borrow the pattern without Alexandria

Keep a voice.json, a brand.json, and a few short context notes in your repo, and attach them to any model or tool at the start of a task, the way /voice-check attaches an article. You won’t need an endpoint or a key, and your agents will stop guessing at your voice.