AlexandriaA Library grows by what you feed it. No forms: you talk to it in the window you installed it from, and a backlog on disk comes in as one batch. Everything you hand it is 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. Four steps, in order; each makes the next 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 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.” 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 People notes you already have, puts names on your message threads, and creates notes only for the people you name. Never 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 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 for free.
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 and apply on their own. Once a day the Library checks for a newer release, verifies it against Keystone's key, and applies it; one it cannot verify is refused. Off switch: alexandria.auto_update: false.
- Skills are machinery, not notes. They live with the software, out of your notes, out of the graph, out of search; every one starts with ax-.
- The Library ships no Obsidian plugins and turns none on. Saving and syncing are its own job; Obsidian stays optional and its plugins stay your choice.
- Email is read through the mail connector your chat app already has. The Library holds no mail password, and it never sends.
- 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. A push from a paired Library is captured to your inbox with the sender's suggestion attached; you file it where it belongs or decline it — nothing files itself, and the sender's receipt says which.
- Mac-local sources, Messages, WhatsApp, Viber, 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 Desktop? Same motions. The playbooks live as plain files in .alexandria/skills/ (and as .claude/skills/ adapters), and the folder's AGENTS.md points any agent at them.
The skills on board
Every skill is also a command, and every one the Library ships starts with ax-. Type /ax in the chat window to list them all, then pick one: /ax-ingestion, /ax-settings, /ax-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
tune anything: your agent's name 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, never overlapping
4.3.5how the Library is doing, in one read: growth (notes, words, size, what is new), hygiene (broken links, convention drift), and a tidy of the empty files Obsidian leaves in the root
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; a long push is a packaged note from the outbox, and what arrives waits in your inbox for review
deprecated in 4.4: ax-messages answers what needs you, across mail, texts, WhatsApp and the relay; this one goes in the next minor release
4.3.5one read-only read across your email (through your connected Gmail), iMessage, WhatsApp, Viber, and what other Libraries pushed to yours: what did X send me, what needs a reply, one thread in full
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
keeps the Library current: a signed release is checked for daily and applied on its own; say "update my brain" for one now; your notes are never touched, 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
5.0what is on your mind for tomorrow, or the day's priorities, captured into that day's note: the night-before and morning-of planning pass
5.0connects one of your mailboxes, read-only, entirely in conversation: Gmail, iCloud, Fastmail or plain IMAP; the password goes into a native window, never into chat
5.0is this work theater? a per-day audit of where the day's effort went, tracked over time
5.0checks the relay: pulls what paired Libraries have pushed to yours and reads it as mail, held for your review
5.0learns how you write as you use the Library and keeps a voice guide, so every draft in your name sounds like you · the guide
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 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 ask “how is my Library doing?” now and then; 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 Library's own sync routine pushes and pulls once a remote is set; no Obsidian plugin is involved), 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, Viber, Contacts, Photos, and Screen Time are read where they live, on the Mac you are asking from, never on a server. Email is not one of them: it is read through your chat app's mail connector, with nothing to grant and nothing stored in the Library. One grant covers the Mac stores: System Settings, Privacy & Security, Full Disk Access, for the app running the assistant, Claude Desktop; then reopen it. 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. Viber is read from Viber for Mac when its store opens, else from the iPhone's iCloud backup mirrored on the Mac; a backup read ends at the backup, and the agent says when it was taken. 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.
Staying current
The Library updates itself. The first time it opens or updates, it installs a small launchd timer on your Mac; once a day the timer checks keystone.computer for a newer signed release and applies it: the release is verified against Keystone's key, whatever you were editing is committed first as its own commit, the software is swapped with the previous version kept one rollback away, and the Library re-renders its own machinery. Your notes and settings are never touched. “Update my brain” does the same now, and tells you what changed. Off switch: alexandria.auto_update: false in Agent/config.json; alexandria autoupdate status shows the timer.
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.
Since 4.0Federation: link two Libraries and push between them
Two people who each run a Library 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; nothing to enable, 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 arrives as data in a fixed schema, checked against the permissions you granted them, and 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 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 for this, so nothing ticks until you ask, say “anything from Jane's Library?”, 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.