axi25-core

AXI25 Core

The harness-agnostic operating system for a personal, AI-operated knowledge vault.

One versioned source of truth — skills + contract + reference docs — that projects into any vault so the same behavior runs on Claude Code · OpenAI Codex · OpenCode · Pi, with zero setup.

What is this?

A wiki-llm vault is the persistent memory of one specific human operator: the compounding record an AI reads so it stops restarting from zero every conversation. AXI25 Core is the behavior of that vault — the Agent Skills, the operating contract (AGENTS.md), and the reference docs — packaged as a single, versioned unit.

Your vaults hold data. This repo holds behavior. A thin wire step projects the behavior into each vault, in exactly the shape every agent harness expects. Fix a skill once here, and every vault that consumes it gets the fix — no more copies drifting apart.

Quickstart

# scaffold a fresh vault (folder tree + anchors) and wire the core into it
npx @axi25/core init my-vault

# then open my-vault/ in your agent and type:  onboarding

Already working in Claude Code, Codex, OpenCode or Pi? Install the 14 skills, then scaffold the vault and its AGENTS.md contract in the same folder:

npx skills add felipefontoura/axi25-core
npx @axi25/core init .

# then open the folder in your agent and type:  onboarding

Skip the second command and onboarding still runs, but it builds a thinner vault by hand: no AGENTS.md, no docs/, and only the three page templates it writes itself.

In an existing vault:

npx @axi25/core wire      # (re)project the current core
npx @axi25/core update    # pull a newer core version
npx @axi25/core verify    # CI guard: assert the projected files still match the lockfile
npx @axi25/core doctor    # check environment + core freshness

Requires Node ≥ 18 — that is the whole runtime. No other install.

Want the complete, ready-to-use vault (Obsidian AI panel, docs, guided setup) instead of a bare one? Use @axi25/vault: npx @axi25/vault@latest init my-vault.

As a Claude Code plugin

/plugin marketplace add felipefontoura/axi25-core
/plugin install axi25@axi25

Installs the 14 skills. As with npx skills add, run npx @axi25/core init . in your vault folder to get the full vault and its AGENTS.md contract.

Supported harnesses

What's inside

14 Agent Skills — the operating loop of the vault:

capture · ingest · process · journal · study · worklog · query · lint · review · plan · onboarding · doctor · core · source

The standout is axi25-source — cloud-first source acquisition. It turns any raw media into clean, faithful Markdown using pip packages + one OpenRouter API key and no heavy local ML:

• Books — PyMuPDF for digital PDFs, open-weight vision OCR for scanned/garbled ones, markdownify for epub.
• Complex designs (slides, mind maps, infographics) — vision design mode reconstructs the information architecture, not a flat transcription.
• Web — trafilatura (local, no key).
• Audio & video — OpenRouter transcription + speaker diarization with name inference.

Every model default was chosen by a cost-vs-quality bake-off, not by taste.

How it works

The core lives in skills/, references/, and AGENTS.md. wire projects it into a vault as real copies (never symlinks — Windows-safe), guided by one declarative table (PROJECTIONS in bin/axi25.mjs), and writes a lockfile (.axi25-lock.json) of content hashes. verify fails if a projected file was hand-edited or the core drifted — hashes are canonicalized (EOL/BOM/case) so the result is byte-identical on Linux, macOS, and Windows (proven by the CI matrix).

Two consumption models, one repo, identical output:

→ Design rationale: docs/architecture.md · operational runbooks (update a vault, repoint, release): docs/maintenance.md.

Data handling and privacy

• Your notes stay on your machine. The skills read and write plain Markdown in your own vault. Journal and capture notes can contain personal data; nothing is uploaded unless you use the one skill below.
• No backend, no accounts, no telemetry. The maintainer receives and retains nothing. The CLI makes no network calls.
• One skill sends data off your machine: axi25-source, and only when you ask it to acquire a source. Depending on the input it sends audio (transcription, speaker diarization), page images of scanned PDFs (OCR) or text (cleanup) to OpenRouter, which routes it to the model provider, using your own OPENROUTER_API_KEY. The key is read from your environment or from the skill's own scripts/.env and goes only to openrouter.ai. Retention is governed by OpenRouter's and the provider's terms. Don't use the skill and nothing leaves.
• URL sources are downloaded from the address you give (articles, videos). The optional --cookies argument takes a cookie file you point to; the skill never looks for browser cookies on its own.
• axi25-doctor installs tools only after your explicit "yes", with the exact command shown first.

Questions or concerns: open an issue.

Contributing

Contributions are welcome — see CONTRIBUTING.md. The golden rule: edit the source in skills/ and references/, never the projected copies; wire regenerates them, and npm test enforces both the projection lock and Agent Skills spec conformance.

By participating you agree to our Code of Conduct. To report a vulnerability, see SECURITY.md.

License

MIT.