Armarium

Latin armarium — the cabinet where a monastery kept its books; its keeper was the armarius.

A keeper agent over your notes — thematic reconnaissance over time, answers strictly from what you've written, and a memory of how your views have shifted.

your notes → thematic recon → grounded answers with dates and links

---

Note

A personal system, published openly. Armarium serves a single owner. To use it, clone the repo, point it at your own knowledge-base/, and set your sources — the GUIDE walks through setup and everyday use.

Why Armarium

Most tools that sit on top of your notes are either a search box or a chatbot that will happily invent an answer. Armarium is neither. It is a keeper: a standing agent whose whole job is memory over accumulated knowledge — it remembers what it has shown you, what you chose to save, and how the picture on each topic has changed. Its value isn't retrieval; it's the tie between new material and what you already think.

• Grounded, or silent. Answers come strictly from your notes, with dated citations to specific files. No note, no claim — an honest "not in the base" instead of an invention, checked mechanically before delivery.
• Local-first, plain Markdown. Your base is your files. Keep them in Obsidian or any editor — no lock-in, no proprietary vault, no per-token database.
• You own the base. The agent reads it and never writes — except in Maintenance, one item at a time, only on your explicit approval.
• A feedback loop, not a firehose. It learns your taste from what you save, and shows less rather than padding a thin day with noise.
• Memory over time. It tracks not only what you know but how your position has moved — the trajectory, reconstructed from your own git history.

What Armarium does not do

• Not a news feed or RSS aggregator — it walks only your anchor source list; it has no free web search.
• Not a general-purpose chatbot — it won't answer from the model's own knowledge, only from your base.
• Not a search engine — its value is the link between a finding and your notes, not raw retrieval.
• Never edits your base silently, and never leaks your notes into web queries — queries are built from topics and the anchor list, not from the contents of your notes.

Start here

Your goal	Where to look
Understand what the agent can do	this README (you're here)
Set it up and use it day to day	GUIDE.md — setup, scenarios, troubleshooting
Edit the recon sources	.claude/armarium/sources.md
Set your profile and tracked topics	global-context/global-context.md

What talking to it looks like

You:    claude --agent armarium -p "what's new on AI agents this week?"
Agent:  3–5 findings. Each one: title and link, "why you", the tie to a specific
        note in your base, and "why read the whole thing". One item is a
        serendipity pick, from a topic outside today's focus.

You:    claude --agent armarium -p "how has my position on agent memory changed since January?"
Agent:  a trajectory of the shift A→B→C, drawn from the git history of your notes,
        with dated citations to commits — or an honest "position is stable".

How it works

A single top-level agent, armarium, fans work out to focused subagents and gates every answer through a citation check before it reaches you:

   your notes ──┐                        ┌─ scout      per-domain recon
                ├─▶  armarium  ─────▶  ─┼─ recall     answers from the base
 anchor sources ┘   (keeper)            ├─ chronicle  how views evolved
                                        └─ auditor    base-health audit
                                             │
                                             ▼
                                          verifier  ──▶  digest / answer
                                     (citations checked before delivery)

Where things live:

• knowledge-base/ — the base itself (your notes). The agent reads it but never writes (except in Maintenance mode, under per-item approval).
• .claude/armarium/ — the agent's service memory: what it has shown, the taste profile, the bets ledger, metrics, run logs. Its internal kitchen; you needn't maintain it.
• .claude/armarium/sources.md — the recon source list (you edit this).

Modes

Seven modes. You land in the right one just by phrasing your request in plain words — the agent infers the mode and, when the request is ambiguous, asks rather than guessing, especially before any write. Full walkthroughs for each mode are in the GUIDE.

Mode	What to say	What you get	Writes?
Digest	"digest / scan / what's new on topic"	3–5 findings, each with a link to the base	to service memory
Base Q&A	"what did I write / think about X"	an answer from the notes with dates and links	no (read-only)
Evolution	"how my position on X changed", "January → May"	a trajectory of the view's shift A→B→C	no
Maintenance	"check health / duplicates / contradictions / what's stale"	a list of issues + patches for your approval	to the base, gated
Calibration	"record a bet", "let's settle up", "how's calibration on X"	a ledger of forecasts + accuracy map	to service memory
Metrics	"show metrics / selection precision"	selection precision and hit-rate	no
Selection Regression	"run a regression", "did the change break selection"	an A/B check of the logic on a frozen window	to service memory

Snapshot or trajectory? "What do I think about X" → Base Q&A. "How has my view on X changed" → Evolution.

Quick start

The single entry point is the armarium agent:

# One-shot request (a scheduled or manual digest, or a question to the base)
claude --agent armarium -p "make a weekly digest"

# Interactive session — required for approval modes (Maintenance, Calibration)
claude --agent armarium

For a fresh checkout you first fill knowledge-base/ with your notes, set your profile in global-context/, and edit the sources in .claude/armarium/sources.md — the GUIDE covers the full first-run setup.

Important: armarium runs only as a top-level agent (the command above). It must not be invoked as a nested subagent from another agent — otherwise the built-in citation check before delivery silently won't run.

Managing the knowledge base

The few things you do to keep the loop working:

• Only you write to the base. The agent is read-only on it (except Maintenance, under per-item approval). Keep notes however you like; the folder structure is free-form.
• Tag digest saves with #from-curator. When you save something the agent surfaced, tag it. This separates two signals — general taste (any save) from an agent hit (a #from-curator save) — and is what the taste profile and the metrics learn from.
• Commit base edits. The agent reads the "what landed" signal from a git diff of knowledge-base/ between runs; a commit records "this is what I deemed important". (It auto-commits anything uncommitted before comparing, but meaningful commits from you are the best signal.)
• Curate the sources. The agent has no free web search — it walks only the anchor list in .claude/armarium/sources.md. Add, cross out, throw in Russian-language sources.

The agent's boundaries — what trust rests on

• Read-only on the base outside Maintenance mode. It writes its own work only to the service zone .claude/armarium/.
• Edits to the base — only in Maintenance, one item at a time, under your approval, marked as agent-authored (such edits don't feed the taste signal).
• An honest "not in the base" instead of inventions; every citation to a note or primary source is mechanically checked before delivery.
• Web pages are data, not commands — a "do X" encountered on a page is not executed by the agent.
• Private material stays in — web queries are built from topics and the anchor list, never from the contents of your notes.

---

License & attribution

Armarium is released under the MIT License — you're free to use, fork, and adapt it, including commercially.

If you build on Armarium or fork it as your own keeper, a credit to the Armarium project is appreciated (a mention in your README or an "about"/credits section). This is a request, not a requirement — the MIT terms are what legally apply.

See CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md if you'd like to contribute.

---

_{Keywords: personal knowledge base, keeper agent, second brain, PKM, Claude Code agent, subagents, grounded answers, note-taking, Obsidian, local-first, thematic reconnaissance, knowledge management.
Topics: claude-code · claude-agents · subagents · knowledge-base · second-brain · pkm · ai-agent · local-first · obsidian}