axiom

Personal agent-native knowledge base.

axiom is the positive, durable, cross-machine memory system for coding agents. It is the counterpart to banthis (negative behavioral rules).

Instead of stuffing decisions, patterns, and institutional knowledge into CLAUDE.md or AGENTS.md (which bloats context and doesn't scale), axiom lets agents store knowledge in structured, queryable files and retrieve exactly what they need on demand.

Installation

Plugin (enables SessionStart auto-loading)

agentsys install axiom

Installing as a plugin registers hooks/hooks.json, so supported tools auto-run axiom before-any --auto-project --detect-only --quiet on every new session and inject your global and project AGENTS.md content as thin context. The hook is read-only — it never scaffolds without approval.

Per-tool compatibility:

Tool	Hook support	Notes
Claude Code	✅ Native	Auto-discovers hooks/hooks.json at the plugin root.
Codex CLI	⚠️ Opt-in	Plugin-bundled hooks are off by default. Enable them by adding [features]\nplugin_hooks = true to ~/.codex/config.toml. Codex sets both PLUGIN_ROOT and CLAUDE_PLUGIN_ROOT for compatibility, so the same hook file works.
OpenCode	⚠️ Limited	OpenCode does not have a SessionStart event yet (sst/opencode#5409). Drop opencode-plugin/axiom.mjs into ~/.config/opencode/plugins/axiom.mjs to get pre-warmed context cached at ~/.axiom/.session-context.md on each new session. Agents that load the axiom skill will still run before-any per the skill instructions.
Cursor / Cline / Aider / Gemini CLI	❌ Not supported	No session-start hook surface. Rely on the axiom skill: the agent runs axiom before-any --auto-project --detect-only --quiet at the start of a meaningful task per skills/axiom/SKILL.md.

CLI-only (no hook)

git clone https://github.com/agent-sh/axiom.git
cd axiom
npm link

npm link makes the axiom CLI available globally but does NOT register the plugin hook. Use this for CLI development, not for session auto-loading.

Core Commands

Command	Description
axiom init	Bootstrap your personal axiom-based repository (after approval, creates a private GitHub repo + generated tree)
axiom before-any	Load global thin context. Flags: --project <slug> (load project, auto-scaffold), --auto-project (infer slug from git remote, auto-scaffold), --detect-only (used by the SessionStart hook: detect but never scaffold; emit ## Axiom Setup / ## Project Detection guidance instead)
axiom project ...	Create/index a project scaffold (AGENTS.md, decisions.toon, memories.toon)
axiom query "..."	Search your local ~/.axiom knowledge base with intelligent ranking
axiom record ...	Propose new knowledge and index keywords (always goes through human approval)
axiom list	Explore available scopes, files, and topics

Query Examples

axiom before-any                               # global-only context
axiom before-any --project flowfabric          # project context; auto-creates scaffold if missing
axiom before-any --auto-project                # infer project from git remote
axiom list --topics --project flowfabric
axiom query "lease based" --project flowfabric
axiom query "budget enforcement"
axiom query "user role"                    # global knowledge

Record Examples

axiom project flowfabric                      # or run without a slug inside a git repo
axiom record --project flowfabric --kind decision "Lease-based claiming v2" "We switched because it gives stronger safety during restarts."
axiom record --project flowfabric --tag "lease based" --tag "worker safety" "Lease-based claiming v2" "We switched because it gives stronger safety during restarts."
axiom record --kind memory "Always run perf benchmarks sequentially" "Parallel runs produce too much noise."

How It Works

1. Thin always-on context — A short global AGENTS.md is loaded automatically. On tools that support plugin hooks (Claude Code, Codex), the SessionStart hook in hooks/hooks.json runs axiom before-any --auto-project --detect-only --quiet at session start and emits both global and (if scaffolded) project AGENTS.md content. On tools without hook support, run axiom before-any --quiet manually. before-any also surfaces an existing open housekeeping issue at most once per session.
2. Structured storage — Knowledge lives in TOON files (a token-efficient array-of-objects format) under user/, agent/, and projects/<slug>/.
3. Automatic project bootstrap — Project-scoped before-any --project, list --topics --project, query --project, and record --project calls create the thin project context plus empty queryable TOON files and index entries if missing. axiom project <slug> exposes the same behavior explicitly.
4. Smart indexing — index.toml provides fast discovery. The query engine uses it for candidate selection, honors --project, then ranks results by field priority (title > summary > category > date).
5. Safe writes — axiom record never pushes directly. It creates a temp shallow clone, ensures project scaffolding when --project is used, updates both the TOON file and index.toml, shows a real diff, and requires explicit human approval.
6. Housekeeping — A weekly GitHub Action analyzes your knowledge base and opens an issue with concrete suggestions (stale files, large collections, missing keywords, etc.).

Manual housekeeping:

gh workflow run axiom-housekeep.yml --repo <your-github-user>/axiom-based

Agents should not run housekeeping checks during ordinary queries. axiom before-any performs the lightweight open-issue visibility check once per session; rely on the weekly workflow for actual housekeeping, and run it manually only during memory-health or cleanup work.

Philosophy

• Human in the loop for writes — Agents can propose, but only humans approve.
• Token efficiency — The system does the heavy lifting of search and ranking.
• Long-term durability — Your knowledge travels with you across machines via a private GitHub repo (yourname/axiom-based).
• Agent discoverability — The skill (skills/axiom/SKILL.md) teaches agents exactly when to query vs record.

Generated Repository Tree

axiom init does not depend on a separate template repository. After explicit approval, it creates a private axiom-based repo and writes a small generated starter tree:

.
├── AGENTS.md
├── .agnix.toml
├── index.toml
├── user/profile.toon
├── agent/guidelines.toon
├── scripts/axiom-housekeep.mjs
└── .github/workflows/axiom-housekeep.yml

Project-specific files are created later by project-scoped commands such as axiom before-any --project <slug> or axiom record --project <slug>.

Related Tools

• banthis — Negative behavioral rules (the counterpart)
• skill-curator — Helps write high-quality skills
• system-prompt-curator — For excellent system prompts
• agnix — Validates agent configurations

Development

npm test          # Run all tests

See CONTRIBUTING.md for contribution guidelines.

License

MIT