# Alexandria

**Alexandria is the software** that runs a personal Obsidian vault as an AI chief-of-staff "second brain": an operating manual, a structured note-taking system, a daily-digest + maintenance engine, skills, and optional automation — packaged so an agent can deploy and update it for anyone.

Alexandria is the *software*. The in-vault **agent has its own name**, chosen per user during setup (one user might name theirs "Pascal") and stored in config so the agent always knows who it is. Core files never hardcode the agent's name.

> Status: **early build.** The architecture and module layout below are stable; implementation is in progress (see the build plan).

## ▶ Set up Alexandria for someone

**The zero-install path (v3.1):** download **`Alexandria.zip`** from
<https://keystone.computer/install> — or paste
`curl -fsSL https://keystone.computer/install.sh | sh` in a terminal — then open
Claude Code (or ChatGPT Codex) in the unzipped folder and say **"Install"**. The
zip-root prompt provisions the environment and turns the folder itself into the
brain (the vault renders at the folder root; the software tucks into
`.alexandria/`): no accounts, no keys, no technician. Full spec:
[`docs/DISTRIBUTION.md`](docs/DISTRIBUTION.md).
The runbook below is the technician/appliance arc for GitHub-remoted vaults with
emailed digests.

Setup is a **two-role arc** — a **technician** stands up a working, identity-neutral vault ("make it work"), then the **owner** opens it in Claude Code, says **"Hello"**, and personalizes it ("make it mine"). The full role-tagged bucket map is **[`docs/SETUP-ARC.md`](docs/SETUP-ARC.md)**.

Follow the step-by-step runbook in **[`docs/ONBOARDING.md`](docs/ONBOARDING.md)** (laptop) or **[`docs/APPLIANCE.md`](docs/APPLIANCE.md)** (Mac-mini), or send the user the one-click **[`install/install-alexandria.command`](install/install-alexandria.command)** to handle prerequisites + the CLI. **Agents:** use the **`alexandria-install`** skill (in [`.claude/skills/`](.claude/skills/)). The tested path is the `alexandria` CLI (`init` → `secrets` → push + test the digest) — not hand-rendering templates. Working *on the software itself*? See **[`AGENTS.md`](AGENTS.md)**.

## The model: Core / Config / Content

Every file in an Alexandria vault is exactly one of three buckets, with hard boundaries — so updates never clobber a user's work:

- **Core** — the Alexandria system (operating manual, engine code, skills, docs). Authored to be *near-static* and to read **Config** at runtime, so Core is the same for every user and is **replaced wholesale on update**. Lives in the vault's `Agent/` folder (+ root `AGENTS.md`).
- **Config** — the personalization layer: `Agent/config.json` (structured) + Markdown notes (`Identity.md`, `Soul.md`, `User.md`, `Working Style.md`, `Digest Prompt.md`, `Roster.md`). Filled during setup (install, then the owner's interview), read by Core, **never overwritten by update**. The only place customization lives — including the agent's name. *Email addresses are config; only credentials are secrets.*
- **Content** — the user's actual notes (the PEAK pillars + `Daily/` + `Archive/`). Seeded once, then **never touched** by update.

Updates run the genuine renderer, not a hand-copy — and they run **where the software lives**: a zip-installed folder brain updates itself from the latest `Alexandria.zip` (`alexandria update --from-zip` — verified against the published checksum, swap-aside with rollback); a dev checkout pulls itself, then `alexandria update` re-renders (the command is render-only). Either way the in-vault agent drives it from a session ("update my brain"), Core is refreshed, and **Config + Content are never touched**. The few *config-derived* artifacts (the GitHub Actions cron, the pasteable Claude Desktop prompt) are regenerated deterministically from `config.json`. (The old CI lane — a `.state/update-request` trigger commit → GitHub Action → review PR — is retired.)

## Vault structure: PEAK

Not PARA. Four content pillars, named to match:

| | Pillar | Folder | Holds |
|---|---|---|---|
| **P** | People | `People/` | one note per person the owner deals with |
| **E** | Events | `Events/` | year-scoped dated record of state-changes |
| **A** | Areas | `Areas/` | ongoing responsibilities; **Projects nest inside**; the owner's personal area holds `Concepts/` (theses) |
| **K** | Knowledge | `Knowledge/` | neutral subject articles |

Plus three flows: **`Daily/`** (capture in), **`Archive/`** (storage out), and **`Chats/`** (conversation records — `.chat` files, machine-generated). The system folder is **`Agent/`**; machine state is in **`.state/`**. A default **`Areas/Travel`** area carries the schedule (in [Standard Travel Notation](https://wch.io/writing/standard-travel-notation)) that the engine reads to place the owner.

## Install & update

Both are primarily **agent-driven from the Claude UI** (no terminal) via the `alexandria-install` and `alexandria-update` skills; this CLI is the same engine for developers and power users.

```
alexandria init    --vault <path>   # scaffold a new vault (interview → config → Core + Content)
alexandria update  --vault <path>   # refresh Core to latest (Config + Content untouched)
alexandria status  --vault <path>   # installed version, enabled modules, drift
alexandria doctor  --vault <path>   # validate config, secrets, digests, modules, travel schedule
alexandria enable  --vault <path> <module>
alexandria disable --vault <path> <module>
alexandria serve   --vault <path>   # run the brain layer as a server (vault-mcp: streamable HTTP + Bearer seats)
alexandria tool    list|schema|call # the bash surface: the same tool registry vault-mcp serves, no server needed
```

**Agent access — one registry, three faces.** The brain layer (`alexandria_vault/mcp/tools.py`,
59 tools: read / write / agentic / chat / thought / files / metering, seat-gated, path-jailed) is reachable three ways:
**MCP** (`alexandria serve` — streamable HTTP for Claude Code/Desktop and any MCP client,
tailnet-remote via Tailscale Serve), **bash** (`alexandria tool …` — same tools as JSON in/out
for shell agents), and **Python** (`alexandria_vault.vault_core` + the engine entrypoints).
Writes commit to the vault's git history; agentic tools run server-side via `ModelProvider`.

**Model spend & the Library gateway (V3.5, in progress).** Every server-side model call goes
through `ModelProvider`, which honors `ANTHROPIC_BASE_URL` — so a deployment can route spend
through a metering gateway instead of hitting Anthropic directly (the default stays BYO
Anthropic key). The production gateway is **LiteLLM at `llm.keystone.computer` on Railway
(Singapore)**: deployments hold Keystone **virtual keys** with auto-resetting budgets and rate
limits, never Anthropic keys. Its deploy kit lives in [`gateway/`](gateway/)
(as of 2026-07-19: **kit ready, endpoint not yet live** — remaining stand-up steps in its
`DEPLOY.md`). Design record: [`docs/V3.5-GATEWAY-PILOT.md`](docs/V3.5-GATEWAY-PILOT.md).

**Brains — a vault, opened or hosted.** A "brain" *is* an Alexandria vault. Its root is marked
by the `Agent/config.json` sentinel — the server keys on **that**, not on a file extension. The
Orion desktop opens one locally as a **`.brain` bundle** (a folder macOS treats as a
double-clickable document; the desktop strips the `.brain` suffix for display) or as a plain
folder, and connects to a **remote/hosted** one over vault-mcp (a server URL + a Bearer seat
token). **One brain = one vault = one `vault-mcp` process.** So a server does **not** hold "one
`.brain` for all its brains": to host **many**, the V5 rack (`rack-runtime/`) runs **N** brains
behind a hostname router — each its own container + vault (`/data/vault`, rendered by `alexandria
init` or cloned from a git remote) — listed in a `tenants.yml` **registry** that `provision.py`
turns into the running rack. Any one tenant's vault stays portable: it can be exported as a
`.brain` bundle (or the durability backend's single-file git bundle) and opened on the desktop.

**The system picture.** This repo is one plane of three: the **Orion desktop** (the V4
Electron UI — files, chat, graph) opens brains locally or over vault-mcp, and every surface
burns tokens through the **LiteLLM gateway** on scoped virtual keys. What runs where, how the
planes wire together, and each component's current state: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).

**Package the macOS installer** — a self-contained `.pkg` that carries the whole repo (no clone or GitHub auth just to get the files), installs it to `~/Library/Application Support/Alexandria/app`, and launches setup:

```
bash install/build-pkg.sh          # → dist/Alexandria-<version>.pkg
```

Unsigned, so recipients right-click → Open the first time; signing + notarization steps are in [`install/pkg/README.md`](install/pkg/README.md).

**Uninstall** — remove the software + local settings (leaves your vault, tools, and Claude Code config alone):

```
bash "$HOME/Library/Application Support/Alexandria/app/install/uninstall-alexandria.command"   # add --yes to skip the prompt
```

## Modules

`core` is always on. Pick exactly one **automation-runner**:

- **laptop-github-actions** — serverless daily digest + inbound IMAP poll via GitHub Actions cron (no always-on machine).
- **server-macos** — always-on macOS host: launchd schedules, SSH `digest-now`, real-time IMAP IDLE.

Optional features: **team-digests** (per-person briefs for teammates), **principal-inbox** (email your own vault — notes & attachments captured into Daily, plus todos/feedback), **attention-digest** ("what needs me" triage), **federation** (securely exchange TODOs/knowledge with peer vaults over authenticated email), **imessage** (read-only, local iMessage/SMS), **news** (diverse-source world briefings, corroboration-labeled), **screentime** (read-only local Screen Time — "where did my time go"), **screenshots** (Photos-library screenshot sweep → inbox → read-and-triage; read-only, local), **contacts** (macOS Contacts → names for the readers, People-note fill-in, selective People notes; read-only against Contacts), **whatsapp** (read-only, local WhatsApp — the native Mac app's store).

## Retrieval

How a brain finds things — `rg` first-class, the `vaultq_*` verbs by need, and the `retrieve` subagent every rendered vault ships — with the measurements behind each choice: **[`docs/RETRIEVAL.md`](docs/RETRIEVAL.md)**.

## Repo layout

```
scripts/               # the CLI/engine package (NOT rendered into vaults)
alexandria_vault/      # the runtime package — vault_core / models / engine / mcp (the brain)
template/
  core/                # the always-on Core module + Config/Content seeds
  modules/<id>/        # optional modules
modules.yml            # module registry
brain/                 # portable vault-mcp container — host-anywhere image + DEPLOY.md
rack-runtime/          # V5 multi-tenant rack — hostname router → N per-tenant brains
```

## Digests

Two audiences, both configured in `config.json` (addresses, not env vars):

- **owner_digests** — area-routed digests for the owner (e.g. one area → email X; three areas → email Y; the rest → email Z).
- **team** roster — per-person briefs for teammates, each scoped + sent in their own timezone, with an optional reply path.

## Changelog

Release notes live in **[`CHANGELOG.md`](CHANGELOG.md)** — every version bump adds an entry (see AGENTS.md → *Versioning & release notes*), and the launch screen shows the current version's notes.
