axiom

name

axiom

description

Use when working with the user's durable, queryable knowledge base: retrieving past decisions, preferences, recurring patterns, project context, or memories; starting work on a familiar project where previous context may matter; creating/indexing missing project scaffolds; listing available Axiom knowledge; recording durable knowledge the user explicitly wants remembered; or responding to Axiom SessionStart hook signals (`## Axiom Setup`, `## Project Detection`) that ask whether to run `axiom init` or `axiom project SLUG`. Covers axiom before-any (including `--detect-only`), project, query, list, the human-approved axiom record flow, and the SessionStart hook auto-load behavior.

Axiom

Use axiom to keep always-loaded context tiny while retrieving or recording durable knowledge on demand. Local reads use ~/.axiom; record writes use a temporary shallow clone of <handle>/axiom-based unless --local is supplied for development.

Repository Locations

• The user's private knowledge base lives locally at ~/.axiom and remotely at <handle>/axiom-based.
• axiom init --yes creates or refreshes that private repo after explicit approval; it does not use a public template repo.
• The Axiom plugin/CLI source repo is separate. For this project it is /home/avifenesh/projects/agent-sh/axiom (agent-sh/axiom).
• Do not create Axiom knowledge files inside arbitrary project repos. Use ~/.axiom/projects/<slug>/... through the CLI.

Auto-Loading At Session Start

Axiom ships a SessionStart hook (hooks/hooks.json + hooks/session-start.mjs) that runs axiom before-any --auto-project --detect-only --quiet on every new session for tools that respect the standard plugin hook format (Claude Code, Codex). The hook never mutates state; it emits guidance the agent must act on:

• ## Axiom Setup block — appears when ~/.axiom is missing. Ask the user whether to run axiom init. Do not run it without explicit approval.
• ## Project Detection block — appears when the current git remote maps to a slug that has no scaffold yet. Ask the user whether to run axiom project <slug>. Do not scaffold without approval.
• ## Global and ## Project: <slug> blocks — the always-on context. Treat these as already loaded; do not re-run before-any unless the user asks.

If a tool does not support SessionStart hooks, fall back to running axiom before-any --auto-project --detect-only --quiet manually at the start of a meaningful task.

What To Load When

0. If no Axiom knowledge base exists (signal: ## Axiom Setup block from the SessionStart hook), explain that axiom init creates a private <handle>/axiom-based GitHub repo and a small generated starter tree. Ask for explicit approval before creating it. After approval, use:

   axiom init --yes
   

1. At the start of any meaningful task, the SessionStart hook has already loaded global context. If running manually (or the hook did not fire), use the same command the hook does so the behavior matches:

   axiom before-any --auto-project --detect-only --quiet
   

   This is also the once-per-session place where Axiom may surface an already-open housekeeping issue. Strip --auto-project if you want global-only context with no project detection.

2. When working inside a known repo or the user names a project, the SessionStart hook auto-detects from git remote in --detect-only mode (no scaffold mutation). If the project is already scaffolded, its AGENTS.md appears in the hook output. To load it manually:

   axiom before-any --project <slug>
   

   Use the repo slug when obvious, for example axiom for /home/avifenesh/projects/agent-sh/axiom. axiom before-any --auto-project (without --detect-only) infers the slug from the current git remote AND creates the scaffold silently — use it only when you have user approval to create the project. axiom before-any --auto-project --detect-only is the read-only variant the SessionStart hook uses; it is safe to run without approval.

3. When the SessionStart hook reports ## Project Detection (project detected but not scaffolded), ask the user whether to add it to Axiom. After approval:

   axiom project <slug>
   

   Project-scoped list, query, and record calls also auto-create scaffolds, but before-any --detect-only deliberately does not — scaffolding waits for explicit user approval.

4. When the task depends on prior decisions or preferences, query details after loading thin context:

Query Correctly

• Prefer --project <slug> when the request names a repo/project or when you are inside a known repo.
• Query with the phrase future agents are likely to search for, not a whole paragraph.
• If the first query is empty, run axiom list --topics [--project <slug>], then try one alternate keyword before reporting no record found.
• Treat list as discovery only; use query for the actual answer and cite the source path from query output.

Where Records Go

• Project decisions: axiom record --project <slug> --kind decision ... writes projects/<slug>/decisions.toon.
• Project memories, repo paths, gates, operational notes, and reusable debugging context: --project <slug> --kind memory writes projects/<slug>/memories.toon.
• Global user/profile facts: no --project, use --kind profile or --kind fact; writes user/profile.toon.
• Global agent behavior rules/preferences: no --project, use --kind guideline; writes agent/guidelines.toon.
• General global memories: no --project, use --kind memory; writes user/memories.toon.
• If the knowledge is about a specific repo, almost always record it project-scoped.

Indexing And Insertion

• Do not edit index.toml manually in normal use.
• axiom project <slug> and project-scoped before-any, list, query, and record ensure project files and index entries exist.
• axiom record appends the TOON row and updates index.toml from the title, summary, kind, project, and explicit tags.
• Add --tag values for synonyms, old names, acronyms, deleted repo names, or phrases future agents may search for.
• Let axiom record show the diff and wait for explicit approval; never bypass the approval prompt.

Housekeeping

• Housekeeping is a scheduled GitHub Action in axiom-based, not part of normal query/record flow.
• The normal automatic cadence is weekly. axiom before-any may show an already-open housekeeping issue once per session; ordinary axiom query, list, and record do not check housekeeping.
• In a health/cleanup conversation, reuse the before-any notice when present. If you need to check manually, do it at most once per session.
• It can also be started manually with:

  gh workflow run axiom-housekeep.yml --repo <handle>/axiom-based
  

• Mention an open housekeeping issue only when the task is about Axiom health, stale/noisy/missing memory, cleanup, bulk records, schema/index changes, or repeated weak query results across a session.
• If an open housekeeping issue exists, point the user to that issue instead of recommending another run.
• Recommend a manual run only when there is no open issue and there is a concrete health reason. A single empty query is not enough.

Project Slugs

• Use the repo/project name as the slug unless Axiom already lists a different one.
• For this project, use --project axiom; it loads the Axiom-specific invariants, repo paths, and verification commands.
• Project-scoped before-any --project, list --topics --project, query --project, and record --project calls ensure the project scaffold automatically.
• If a project-scoped query still returns only scaffold/index results, record real durable project knowledge through axiom record.

Recording Rules

• axiom init --yes is only for a user-approved setup flow; do not run it speculatively.
• Keep title short and summary to one clear sentence.
• Add explicit --tag keywords when future search terms may differ from the title.
• Let the command show the TOON and index.toml diff.
• Require explicit human approval; never bypass the y/N prompt.
• If writing for someone else's repo, determine --handle with gh api user --jq .login, the current git remote, or by asking. Do not guess.

Examples

axiom project flowfabric
axiom list --topics --project flowfabric
axiom query "lease based" --project flowfabric
axiom record --project flowfabric --kind decision --tag "lease based" "Lease-based claiming v2" "We switched because it gives stronger safety during restarts."

Avoid

• Do not dump large context into AGENTS.md, CLAUDE.md, or the chat when a focused query is enough.
• Do not record trivia, temporary observations, or unverified guesses.
• Do not treat list output as the answer; query the underlying records when details matter.