AlexandriaAn Alexandria Library grows by what you feed it. There are no forms; you feed it by talking, in the same window you installed it from, and a backlog you already hold on disk comes in as one batch. Everything you hand it gets broken into pieces and filed into PEAK structure: people, events, areas, knowledge. Nothing files until you approve the plan.
The first hour
A new Library is empty and has nowhere to put anything. Do these four in order; each one makes the next one land better.
- 1.Settings
Name your areas first: the ongoing responsibilities with no end date, a company, a property, a life domain. Five to twelve is the right count. Add the ones you actually run, not the ones that sound plausible; every area is a target the filing and the briefs scan, and one you don't maintain dilutes the routing. Flag any that must never leave the machine. Each area becomes a folder with its own running to-do list.
- 2.Who's who
Tell it the people you deal with most, one line each: “Ana is our accountant.” Who they are and what they are to you. A person named once with context routes itself on every later mention. On a Mac, “import my contacts” does the rest from your address book: it fills the blank fields of the People notes you already have, puts names on your message threads, and creates notes only for the people you name; it never dumps the whole book.
- 3.File this folder
Bring the backlog in one batch: a folder of notes, an Obsidian or Notion export, a directory of PDFs and decks. The agent walks it, reads the documents, files what it can place with confidence, and parks the rest in the inbox for you rather than guessing; you approve in batches, spot-checks rather than item by item.
- 4.Debrief
Then start the daily habit. Ten minutes at the end of the day is the richest feed the Library has, and the one that keeps it current without effort.
Every day after
What happens inside
- Notes are plain Markdown in a folder you own, ~/Alexandria; readable in any editor and browsable in Obsidian.
- Structure is PEAK: People · Events · Areas · Knowledge, plus a daily layer.
- Nothing files without your approval; the Library proposes, you confirm.
- Every change is a git commit: full history, nothing silently lost.
- Updates are signed. The Library verifies every release against Keystone's key before it applies, and refuses one it cannot verify.
- Nothing leaves the Library except on your command. Federation is push-only and owner-fired; a peer can never read, query, or pull from it.
- Nothing a peer sends is filed without your approval either. Since 4.3 a push from a paired Library is captured to your inbox with the sender's suggestion attached; you file it, approve it as-is, or decline it, and the sender's receipt says which.
- Mac-local sources, Messages, WhatsApp, Contacts, Photos, Screen Time, are read on demand from a snapshot copy, read-only, with no accounts and nothing exported; one Full Disk Access grant covers them all.
Using ChatGPT or another agent instead of Claude Code? Same motions. The playbooks live as plain files in Agent/skills/, and the folder's AGENTS.md points any agent at them.
The skills on board
Every skill is also a command. Type / in the chat window to list them, then pick one: /vault-ingestion, /settings, /pair-with-brain. Saying it in plain words works the same.
file anything you paste; the propose-then-approve pipeline behind “file this”
logs a thread's outcome into today's note: what got done, what's open, every note touched
the daily brief, immediately: regenerates the Action Board and reads out what's open off the freshest vault
tune anything: your agent's address and voice, your details, your areas
everything the Library can do and how to ask for it
structured retrieval: resolve a person, trace links, route a fact
draws the Library as a picture and a live pane; folder-colored, force-laid-out, and in 4.0 never overlapping
how the Library is growing: notes, words, links, tokens
convention and link hygiene; catches drift before it spreads
sweeps stray empty notes out of the vault root; the Untitled files Obsidian leaves behind
4.0links your Library to another person's, hands-off: you relay a five-word code and compare three words, it runs the rest
4.0pushes a to-do, note, fact, or event into a paired Library, end-to-end encrypted; the agent stages, you fire; since 4.3 a long push is a packaged note from the outbox, and what arrives waits in your inbox for review
inbound triage on demand: what needs you across mail, chat, and calendar, ranked
reads your local iMessage history, read-only: what did X text me, what needs a reply; names come from your Contacts
a world briefing from many newsrooms at once; cross-checked, never single-sourced
sweeps new screenshots from Photos into the vault; captured, read, and filed
where your screen time went, read locally from this Mac; read-only
4.1your macOS address book into the Library, selectively: fills blank People fields, names your threads, looks a person up, creates notes for the people you name
4.1reads the native Mac WhatsApp app's history, read-only: what did X send me, what do I owe a reply, catch me up on a group
keeps the Library current on its own: every release is signed and verified before it applies, your notes are never touched, and the previous version stays one rollback away
connects the Library to a private GitHub repository; created, pushed, and kept synced; only your notes, never the software
Advanced
Creating areas
An area is an ongoing responsibility: a company, a property, a life domain. It is also the Library's routing backbone; each one becomes a folder with its own note and running to-do list, and finite projects nest inside it. Say “settings” to add one. Be deliberate here. Every area is a target the filing and the briefs scan, so add areas you actually run, not areas that sound plausible; an area you don't maintain is clutter that dilutes routing.
Deep filing
One input usually touches several homes. After a meeting, the notes are the least of it: a good pass updates the person's history, the area's status, the to-do it spawned, a fact worth keeping, and the timeline. Ask for it: “file this, and update everyone involved.” Meetings and calls get their own dated notes. Then ask “where did you put that?” and correct what's misplaced.
Improving ingestion quality
The single biggest lever is the approval step. Read the proposed plan before saying yes, and edit it: merge into an existing note instead of creating a near-duplicate, name the right area, fix a spelling. Give context the first time (“Ana is our accountant”) and every later mention routes itself. Say the status with the fact: “proposed, not agreed”, “as of August”, “my own estimate”. The Library keeps the qualifier attached to the number at every restatement; a fact fed without one hardens into a claim. And have the Library audit itself now and then, integrity checked, growth reported; drift caught early stays small.
Backing up to GitHub
The Library is already a complete git repository; every note and every update since install day is in its history. Say “sync to GitHub” and the agent gives that history an off-site home: it installs the GitHub CLI if needed, hands you the terminal for a one-time browser sign-in (no token ever passes through chat), creates a private repository, sets it as origin, pushes the full history, and records the remote in the Library's config. Only your notes sync; the software under .alexandria never leaves the machine, and a zip-installed Library holds no secrets to leak. From then on, end a session that changed notes with a push and pull before working on a second machine. To stand the Library up elsewhere: clone the repository, then drop a current Alexandria.zip's .alexandria folder in. The repository stays private unless you insist otherwise; everything in it is your notes, readable by whoever can see it.
# one command: creates the private repo, sets origin, pushes the historygh repo create alexandria-brain --private --source . --push# the routine: push after work lands, pull before work on another machinegit pushgit pull --rebase
Your Library on your phone
Once the Library has a GitHub remote, the Claude app reaches it from any device through the GitHub connector: web, desktop, phone. Two steps, once. In Claude, Settings, Connectors, GitHub: authorize the account and pick the Library's repository. Then paste the block from Agent/Standing Context.md into your Claude profile (Settings, Profile), so every chat you start already knows who you are, that you have a Library, and what to read first. After that a question from the phone reads the repository and an edit lands as a commit on main. Pull on the laptop before you work there (the Obsidian Git plugin does this on its own every ten minutes once the remote is set), and never edit the same note from the phone and the desk in one sitting. The connector is the fallback transport: it reads files, not the Library's retrieval tools, so lookups are slower than at the desk and there is no graph. Live editing in Obsidian stays a desktop thing.
Reading your Mac's own stores
Messages, WhatsApp, Contacts, Photos, and Screen Time are read where they live, on the Mac you are asking from, never on a server. One grant covers them all: System Settings, Privacy & Security, Full Disk Access, for the app running the assistant, Claude Code or its terminal; then reopen the app. Until then a read stops with that exact instruction, and nothing else changes. Each store is copied to a temp folder and the copy is queried, so the live database is never opened and nothing in it is ever altered. WhatsApp needs the native App Store app; the old Electron WhatsApp Desktop keeps nothing readable, and the agent says so. Contacts has a fallback that needs no grant: export a .vcf from Contacts, File, Export, and hand it over. Names for your threads live in Agent/scripts/contacts/handles.json, ignored by git; a name you type there by hand beats an imported one.
Feeding it from elsewhere
With an always-on server, the Library gets an address of its own and you can email it from any device: forward a message, send a photo of a whiteboard, dictate a thought. Each arrives as a capture in the inbox, committed on receipt, and files on the next drain. This is the principal-inbox module, off by default; it needs the server module and a mailbox, and the settings interview walks you through both. A local Library has no email channel; in chat it is the same motions.
New in 4.0Federation: link two Libraries and push between them
Two people who each run a Library can hand each other structured work directly, agent to agent, end-to-end encrypted. You push a to-do, a note, a fact, or an event; it arrives in the other Library's inbox for their review, and files with provenance when they say so: (via Jane's vault). Every Library ships push-capable; there is nothing to enable, only one pairing per peer.
Push-only
A peer can never read, query, or pull from your Library. The only thing your Library ever takes in is a sealed envelope it fetched itself from its own mailbox on the relay. A peer's question arrives as a message; you answer by pushing back.
Owner-fired
Content leaves only on your command. The agent stages and shows you the manifest; you fire. The one thing that goes out on its own is a delivery receipt: status only, never content.
Each Library has its own key, generated once and kept outside the vault; its fingerprint, an ax1… string, is its address. The relay at relay.keystone.computer stores only ciphertext and can read nothing. What a peer sends you arrives as data in a fixed schema, checked against the permissions you granted them, and since 4.3 is captured to your inbox rather than filed: the sender's destination rides along as a suggestion, and nothing reaches a note until you act. A peer you trust as an automated feed can be marked auto_apply in the config; that is the one exception, and it is yours to grant.
Say the words and the agent runs every step. The commands below are the same steps by hand: alexandria is the shipped CLI at .alexandria/app/.venv/bin/alexandria, run from the Library folder.
1. Pair, once per peer
Connect me with Jane's Library
You do two things. Relay the five-word code to Jane over a channel you trust, a call or Signal, not email; it expires in ten minutes. Then compare the three verification words with her out loud. If they match on both sides, say so and the pairing confirms. If they differ, say so and it aborts; a mismatch can mean someone is in between, never retry with the same code. Jane's side: she opens her Library and says she has a pairing code. Confirming grants Jane to-dos, notes, and knowledge; calendar events are excluded, and you can narrow the grant later.
# prints the five-word code; send it to Janealexandria peer invite "Jane Roe" --handle jane# "waiting" until she redeems it, then the three wordsalexandria peer check jane# the words match: finalize (both sides do this)alexandria peer confirm jane# the words differ: cancel and revokealexandria peer abort jane
Jane redeems the code on her side, names you as she likes, and confirms the same three words:
alexandria peer add word-word-word-word-word --handle will --name "Will"alexandria peer confirm will
2. Push
Tell Jane's Library: the meeting moved to 3pm
Dictated content, the words already yours, stages and fires in one turn. Composed content, anything the agent wrote that you have not read, stops at the staged manifest: the verbatim payload and where it would land on Jane's side, “files to Acme” or “files to Acme/Q3 brief (its own note)”. You read it, then say fire. A note or a to-do names a target area on her side; a fact her knowledge base; an event her timeline. Anything longer than a line is a packaged note: the agent writes it in Agent/Federation/outbox, a folder the Library ignores for search and the graph, and pushes the file; it lands as its own note on her side, and the push id is stamped back into the package so the file is the record of what went. On the command line the invocation is you, so push stages and fires at once. One push carries up to 8 MiB, a full 1M-token context window, so a whole note goes in one piece; anything larger is refused at staging and the agent splits it into smaller pushes rather than trimming it.
# a to-do onto Jane's list, in her Acme areaalexandria push jane --as todo --area Acme --due 2026-09-05 \ --text "Send the Q3 deck by Friday"# a notealexandria push jane --as note --area Acme \ --text "Rescoped the audit to the US entities"# a packaged note from the outbox; lands as its own note in her Acme areaalexandria push jane --as note --area Acme \ --file "Agent/Federation/outbox/2026-09-03 Audit brief for Jane.md"# a whole note as knowledge (a path inside your Library)alexandria push jane --as knowledge --file "Areas/Acme/Audit scope.md"# an eventalexandria push jane --as event --date 2026-10-01 --text "Board offsite"
3. Receive
Anything waiting for me?
Inbound is pull, and since 4.3 receiving is an ingestion, not a write. Your Library fetches sealed envelopes from its own mailbox, opens them, checks that the sender is a paired peer and the item is fresh, and captures each item to Agent/inbox: the same pending shape as anything else you capture, with the verbatim content, the sender's suggested home, and whether it sits inside the permissions you granted. A receipt goes back saying received. Nothing files until you act. A local Library has no background worker, so nothing ticks until you ask or install the timer.
# one pass: deliver fired pushes, poll, capture inbound, send receiptsalexandria federation tick# mailbox, outbox, per-peer status, and whether anything auto-ticksalexandria federation status# peek at the mailbox, read-only; content vs protocolalexandria peer inbox# macOS: a launchd timer runs tick on an intervalalexandria federation install-timer --interval 600
4. Review, cancel, unpair
What's waiting from Jane?
Three moves, the same as for any capture. File it yourself: say “process my inbox”, the agent reads the capture, proposes where the pieces belong, and deletes the item once you approve; the next tick tells Jane it was applied. Approve as-is: files it where she suggested, with provenance, an owner override that works even outside her grant. Decline: drops it and tells her it was declined, never why. Agent/Federation Review.md is the readable view of what is waiting; act with the verbs or on the inbox item, not by editing the note. A push can be pulled back while it is still staged or fired; once deposited it is in Jane's mailbox and cannot be recalled, push a correction instead. Removing a peer revokes their token at the relay: the block button.
# what is waiting: id, peer, the capture in Agent/inbox, the suggestionalexandria federation review list# file it where she suggestedalexandria federation review approve <id># decline it (she gets a declined receipt)alexandria federation review reject <id># only while still staged or firedalexandria federation cancel <id>alexandria peer list# re-show the three words, on demandalexandria peer verify jane# remove and revokealexandria peer remove jane
On a served Library the same steps are chat tools: peer_pair_invite, peer_pair_join, peer_pair_confirm, peer_stage, peer_fire, federation_tick, federation_review. The full operator guide and security model ship inside the software at .alexandria/app/docs/FEDERATION.md.
© Keystone Context Systems, Inc.