Skip to content

GUIDE.md

Latest commit

 

History

History
314 lines (233 loc) · 12.8 KB

GUIDE.md

File metadata and controls

314 lines (233 loc) · 12.8 KB
Raw

Guide: using Armarium day to day

The README answers what the agent does. This guide answers how to work with it — from first setup to the everyday rhythm — in plain, step-by-step terms. No prior experience with AI agents is assumed; wherever a step touches the terminal or git, it's spelled out and safe to copy-paste.

The mode overview and the trigger phrases live in the README and aren't repeated here.

Contents

Before you start

You need four things in place. Check each once — if a check fails, fix that one thing before moving on, because the rest of the guide assumes all four.

  1. Claude Code is installed and signed in. Open a terminal and run claude --version. If it prints a version number, you're set. If not, install Claude Code and sign in first.
  2. You have a terminal you can paste into. On macOS that's the built-in Terminal app (press ⌘-Space, type "Terminal", Enter). You'll paste one line at a time and press Enter.
  3. Git is available. Run git --version. If macOS offers to install "developer tools", accept — it's a one-time click. Git is what lets the agent see how your notes change over time.
  4. Your notes are in Markdown files. Plain .md files, such as an Obsidian vault. They need no special structure — any folders and any naming are fine.

You do not need to know how to code. Every command below is copy-paste; the guide says what each one does.

Part 1. Setup and first run

Six steps, done once. After this the agent is ready for daily use.

Step 1. Get Armarium onto your machine

Clone the repository — this brings its git history, which the agent relies on:

git clone <repository-url>   # replace with the repo's address
cd ARMARIUM                  # move into the folder you just created

If you downloaded a ZIP instead of cloning, unzip it, open the folder in the terminal, and start its history once:

git init
git add -A && git commit -m "chore: initial armarium checkout"

Step 2. Add your notes

  1. Copy your Markdown notes into the knowledge-base/ folder.
  2. Any layout is fine — subfolders or a flat pile, however you already keep them.
  3. Rule of thumb: the denser your notes on a topic, the better the agent's work on it. A topic with no notes to link against simply returns an empty digest — that's expected, not a failure.

Step 3. Save your notes into git

The agent learns "what you kept" by comparing your notes between runs, and that comparison needs git. Record the current state once:

git add -A
git commit -m "notes: initial knowledge base"

You'll repeat this add + commit pair whenever you want to record new notes — see Scenario A.

Step 4. Set your profile

  1. Open global-context/global-context.md in any text editor.
  2. Fill in who you are, the topics you track, and what counts as noise (things you don't want surfaced).
  3. The agent reads this to judge whether a finding is relevant to you. Update it whenever your focus shifts.

Step 5. Set your sources

The agent doesn't search the open web — it reads only a list of sources you give it (its "anchor list").

  1. Open .claude/armarium/sources.md.
  2. Remove sources you don't care about; add your own — feeds, blogs, sites, in any language.
  3. Optionally check that a feed is reachable (a response means it's alive; remove dead ones): 
    curl -sI https://importai.substack.com/feed

Step 6. First run

claude --agent armarium -p "make a digest"

On the very first run there's nothing to compare against yet, so the agent just assembles a digest without a taste signal. It begins learning your taste from the second run onward — once it can see what you saved after the first digest.

Part 2. Everyday scenarios

Six typical ways to use the agent. Each shows the command, what comes back, and what you do next.

Scenario A. Get a digest and give feedback

The core loop — do this on a regular rhythm.

  1. Ask for a digest: 
    claude --agent armarium -p "what's new on my topics this week?"
  2. You get 3–5 findings. Each has a title and link, "why you", a tie to one of your existing notes, and "why read the whole thing". One pick is a wildcard from outside your usual focus.
  3. Open the sources that interest you.
  4. Save anything worth keeping as a note in knowledge-base/, and add the tag #from-curator on its own line — this marks "the agent found this."
  5. Record it in git: 
    git add -A
git commit -m "notes: saved from digest"

Why the tag and the commit: on the next run the agent sees what you kept, learns it guessed right, and sharpens its taste. Skip them and it can't tell a hit from a miss.

Scenario B. Ask what you already know

  1. Ask: 
    claude --agent armarium -p "what did I write about the unit economics of inference?"
  2. You get excerpts straight from your notes, with file links and dates.
  3. If your notes are silent on it, the agent says so honestly ("not in the base") after re-checking with related words — it won't invent an answer or go to the web.

This is a snapshot: what your archive holds right now. If two notes disagree, it shows both with dates rather than quietly picking one.

Scenario C. See how your view changed

  1. Ask: 
    claude --agent armarium -p "how has my position on agent memory changed since January?"
  2. You get a trajectory — A→B→C — reconstructed from your notes' history, with dates and links to each change. Minor wording edits are separated from real shifts.
  3. If nothing substantive changed, it says "position is stable".

The difference from Scenario B: B is "what I think"; C is "how it moved". For C to work, the topic needs more than one saved version in your history.

Scenario D. Monthly base cleanup

This is the one mode that changes your notes, so it runs as a conversation, not a one-line command — nothing is edited without your yes.

  1. Start an interactive session: 
    claude --agent armarium
  2. Ask it to check the base: 
    check the base for duplicates and contradictions
  3. It returns findings in four classes — contradictions, duplicates, stale notes, missing links — each with a concrete proposed fix.
  4. It presents them one at a time. For each, you say apply, reject, or defer.
  5. It applies only what you approved, marks those edits as agent-made, and remembers your rejections so it won't propose them again.

There is no "apply all" — the base stays under your control by design.

Scenario E. Track a forecast

  1. Record a bet: 
    claude --agent armarium -p "record a bet: by Q4 the price of tokens will halve"
    It's logged with today's date and a due-date for the check.
  2. Later, settle the matured bets: 
    claude --agent armarium -p "let's settle up the matured bets"
    It shows the bets whose date has passed. You call each one hit or miss — the agent never decides, and never makes forecasts of its own.
  3. Any time, ask "how's my calibration on AI?" for an accuracy map by topic.

Scenario F. Check selection quality

  1. Ask: 
    claude --agent armarium -p "show selection metrics"
  2. You get precision (the share of shown items you saved) and hit-rate (counted via #from-curator) over a recent window, with a confidence range.

Metrics only measure — they don't change what the agent selects. A rising hit-rate means it's matching your interests more closely.

Part 3. Rhythm and automation

A rhythm that works

  1. Digest — on a steady beat (for example, weekly). The more regular the rhythm and your feedback, the faster its taste sharpens.
  2. Ask the base / See how it changed — whenever you need it, ahead of meetings or decisions.
  3. Cleanup — occasionally (for example, monthly), as an interactive session.
  4. Forecasts — record them as they come up; settle periodically.

Run the digest automatically

So a digest arrives without you launching it. Two ways:

  1. Recommended — Claude Code schedule. In a Claude Code session, run the /schedule command and follow the prompts. No terminal setup needed.
  2. Advanced — system cron. If you're already comfortable with cron, add a line like: 
    # every Monday at 9:00 — the weekly digest
0 9 * * 1  cd "/path/to/armarium" && claude --agent armarium -p "make a weekly digest"

Only the digest should be automated. Cleanup and forecasts need your decisions, so keep them manual.

Part 4. Safety nets

You don't manage these — they simply protect your runs:

  1. One writer at a time. If you start a second run while one is still writing, the second bows out harmlessly; the next scheduled run picks up where it left off.
  2. All-or-nothing. A run either finishes and moves forward, or leaves no trace — a cancelled run never half-updates "what was already shown".
  3. A run log. .claude/armarium/logs/runs.md records each run's date, mode, and outcome. Check here to see whether a run happened and how it ended.

Part 5. FAQ and troubleshooting

Do I need to be technical to use this? No. You need to paste commands into a terminal and edit plain text files. The four checks in Before you start are the only prerequisites.

Is my knowledge base private? Yes. The agent's web queries are built from your topics and your source list — never from the contents of your notes. Your notes stay on your machine.

The digest came back empty or with only 1–2 items — did it fail? Usually not. A "thin day" is a normal outcome: the agent won't pad a digest with noise — a missing item beats a weak one. If an entire topic's sources were unreachable, it marks that topic "not covered" and shows the rest. Check .claude/armarium/logs/runs.md to see whether a topic went uncovered.

The agent says "not in the base", but I'm sure I wrote about this. Check, in order: (1) the note is really inside knowledge-base/, not elsewhere; (2) it's saved and committed to git; (3) the wording overlaps at least in meaning — the agent re-checks with related words, but a very unusual phrasing can slip past. Try asking again in different words.

I edited notes in Obsidian and the agent "doesn't see" them. Fresh edits are picked up on the next run, when the agent re-reads the base. Make sure the edits are saved and, ideally, committed to git. Changes aren't picked up in the middle of a run already underway.

A scheduled run was skipped and nothing arrived. Most likely another writing run was active at that moment, so the new one stepped aside (the one-writer rule). Nothing is lost — the next run repeats the window. The outcome is recorded in .claude/armarium/logs/runs.md.

The digest showed something I've already seen or rejected. It shouldn't — the agent skips what it has already shown or you've rejected. A one-off repeat usually means a previous run was cancelled before it could record what it showed. It evens out on the next clean run.

How can I tell the agent is learning from me? Tag what you save from a digest with #from-curator and commit your notes — that's the one signal it learns from. Track progress with "show metrics": a rising hit-rate means it's matching you more precisely.

The agent picked the wrong mode or misread my request. Rephrase more explicitly (the trigger phrases are in the README). When a request is ambiguous, the agent leans toward the safe, read-only reading, or asks — it won't start writing (editing notes, recording a bet) on a guess.

Can I undo an edit the agent made during cleanup? Yes. Agent edits carry an authorship marker in the text and in git, so they're easy to find and revert with ordinary git tools.

Can I run armarium from inside another agent? No. It works only as a top-level agent (claude --agent armarium). Nesting it silently skips the built-in citation check that runs before every answer.

I want to add or remove a source. Edit .claude/armarium/sources.md yourself. Check a new feed with curl -sI <address>. The agent has no free web search by design — it reads only your list.

See also: README — overview and mode reference; .claude/agents/armarium.md — the agent's core; knowledge-base/CLAUDE.md — rules for working with the base.