axiom-wiki

v0.9.2

Published

21 days ago

The wiki that maintains itself. AI-powered personal knowledge base that ingests documents, extracts entities, and maintains a structured wiki.

Downloads

313

"Instead of repeatedly querying a raw database with RAG, what if an AI continuously reads, extracts, synthesizes, and compiles your knowledge into a clean, cross-linked, living wiki?"
— Inspired by Andrej Karpathy's llm-wiki thesis.

Why Axiom? (Knowledge Compilation vs. RAG)

Traditional Retrieval-Augmented Generation (RAG) searches raw document chunks at query time and re-derives answers from scratch on every prompt. As knowledge bases grow, traditional RAG suffers from high latency, lost context, missing relationships, and silent hallucinations.

Axiom takes a fundamentally different approach: Knowledge Compilation.

   Raw Sources                                Compilation Pipeline                            Interconnected Wiki
 ┌───────────────┐                            ┌────────────────────────┐                    ┌─────────────────────────┐
 │ PDFs, Docs    │                            │ ⚡ Incremental Ingest   │                    │ 📂 pages/entities/       │
 │ Markdown      │ ─── axiom-wiki ingest ───► │ 🔗 Entity Resolution   │ ─────────────────► │ 📂 pages/concepts/       │
 │ Codebases     │     or autowiki            │ 🏷️ Cross-linking       │                    │ 📂 pages/sources/        │
 │ URLs / HTML   │                            │ 🛡️ Forensic Citations  │                    │ 📂 pages/analyses/       │
 └───────────────┘                            └────────────────────────┘                    └────────────┬────────────┘
                                                                                                         │
                                     ┌───────────────────────────────────────────────────────────────────┴────────────────────────┐
                                     ▼                                                                   ▼                        ▼
                          Interactive Terminal UI                                                  Local Web Server          MCP Server
                       • Slash-command autocomplete                                              • Full-text & vector      • Claude Code
                       • Real-time compile status                                                • Interactive SVG graph   • Cursor
                       • Grounded query mode                                                     • Backlink explorer       • Windsurf

Quick Start

Get your personal or project wiki running in under 60 seconds:

1. Install & Initialize

# Global installation (or use: npx axiom-wiki init)
npm install -g axiom-wiki

# Run interactive setup wizard (Scope, LLM Provider, API Key, Directories)
axiom-wiki init

2. Add Sources & Ingest

Drop PDFs, Markdown, images, DOCX, CSV/TSV, or HTML files into your raw/ folder, then compile:

axiom-wiki ingest

Or clip any web article directly:

axiom-wiki clip https://example.com/article --ingest

3. Or Auto-Wiki an Entire Codebase

Generate architectural blueprints, module guides, and domain concepts for any project folder:

axiom-wiki autowiki

4. Explore & Query

# Launch full interactive terminal shell
axiom-wiki

# Query directly with strict zero-hallucination grounding
axiom-wiki query "How does authentication work across our microservices?" --forensic

# Launch local browser UI with interactive graph and backlinks
axiom-wiki serve --open

Tip: You can use axwiki as a shorthand alias for axiom-wiki.

Key Features

🤖 Autonomous Project Mapping (`autowiki` & `sync`)

Point Axiom at any codebase or document folder. An AI agent explores your file tree, plans an architecture catalog, and constructs comprehensive wiki pages in structured batches. When code evolves, axiom-wiki sync detects Git and content diffs to update only stale documentation.

⚡ Incremental Compilation & State Tracking

Source files are tracked using cryptographically secure SHA-256 content hashes in state.json. Subsequent runs skip unchanged files instantly. PID-based compilation locks guarantee concurrency safety during automated runs.

🛡️ Forensic Citation Proofs & Grounded Querying

Never wonder if an AI hallucinated a fact:

Strict Paragraph Citations: Claims cite exact locations: pages (^[book.pdf#p. 42]), timestamps (^[talk.mp4#14:20]), lines (^[auth.ts#L88]), or exact quotes (^[rfc.txt#"MUST NOT"]).
Claim Grading: Annotate claims by evidence strength (| grade: data, anecdote, outcome, assertion).
Deterministic Audit: axiom-wiki lint --forensic mechanically verifies locators against raw source text, exiting with code 1 on invalid references. Perfect for pre-commit hooks and CI pipelines.
Zero-Knowledge Query Mode: axiom-wiki query --forensic completely bars parametric LLM memory, answering strictly from verified wiki pages and raw sources.

🔍 Orama Hybrid Search & Heading-Aware Chunking

Combines lexical BM25 keyword search with dense vector embeddings using an embedded Orama engine:

Automatically chunks long documents by markdown headings ([Document > Section]).
Two-stage candidate deduplication and dynamic dimension probing.
Seamless embedding support for Google Gemini (up to 3072d), OpenAI (1536d), or Ollama (100% offline).

🌐 Local Web UI & Link Graph (`serve`)

Run axiom-wiki serve to launch a zero-dependency, lightweight web dashboard (http://127.0.0.1:1717):

Dashboard & Metrics: Category distributions, raw document counts, and index health.
Deterministic SVG Graph: Visualize page connections, identify orphan nodes, and spot broken links.
"Linked From" Backlinks: Native bi-directional backlinks on every page.
Read-Only Safety: Zero write endpoints; safe for LAN sharing via --host 0.0.0.0.

🔌 Native Model Context Protocol (MCP) Server

Integrate Axiom Wiki directly with Claude Code, Cursor, Windsurf, or custom AI agents.

16 Core Agent Tools: read_page, write_page, search_wiki, ingest_source, get_backlinks, verify_citations, and more.
Agent Planning Tools: get_architecture_brief, plan_with_wiki, check_before_commit.
Ambient Context Resources: Exposes axiom://overview, axiom://index, and axiom://recent-changes.
Run axiom-wiki setup-agent to automatically configure your favorite developer tools.

💎 Obsidian Compatible & Unix-Friendly

Pure Markdown: Every page is standard Markdown with clean YAML frontmatter. Open wiki/ as an Obsidian vault with full graph and tag support.
Maps of Content (moc.md): Automatically compiled tag hierarchies.
Unix Pipelines: Parse operation logs and token expenditures using standard utilities (grep, tail, awk on log.md and usage.log).

Supported LLM Providers

Axiom Wiki supports 9 providers, from zero-cost free tiers to offline local inference:

OpenAI OAuth Support

Authenticate OpenAI using either standard API keys or browser OAuth:

axiom-wiki auth openai --oauth --activate
axiom-wiki auth status

CLI Commands

Usage: axiom-wiki [command] [options] (or: axwiki)

Knowledge Ingestion & Compilation
  init                         Run the interactive first-time setup wizard
  ingest [file|url]            Ingest a file, URL, or scan raw/ for new files (--interactive)
  autowiki (alias: map)        Autonomously map and build a wiki from a project folder
  sync                         Detect codebase changes and update stale wiki pages
  watch                        Continuously monitor raw/ and auto-ingest incoming files
  clip [url]                   Extract clean article text via Readability into raw/

Exploration & Querying
  query [question]             Interactive chat against your wiki (-f, --forensic for zero trained knowledge)
  serve                        Browse wiki in a local read-only web UI (-p 1717, --open, --host 0.0.0.0)
  graph                        Display ASCII link graph and diagnose broken/orphan links
  sources                      Inspect, reingest, or delete ingested sources
  review                       Audit and resolve conflicting or contradictory facts

Verification & Health
  lint                         Perform wiki health check (--forensic for citation audits, --strict)
  status                       Display wiki page counts, storage size, and index metrics

AI, Embeddings & Agents
  model                        Switch LLM provider or active model interactively
  embed                        Manage vector embeddings (--setup, --reindex, --status)
  auth [provider]              Configure authentication (e.g. auth openai --oauth)
  mcp                          Launch stdio MCP server for Claude Code / Cursor / Windsurf
  setup-agent                  Generate MCP configuration templates for your AI assistants

MCP Server for AI Agents

Turn your wiki into a real-time external memory module for IDE agents like Claude Code, Cursor, and Windsurf.

Automatic Agent Setup

axiom-wiki setup-agent

Manual Configuration

Add Axiom Wiki to your Claude Code configuration (.claude/mcp_settings.json):

{
  "axiom-wiki": {
    "command": "axiom-wiki",
    "args": ["mcp"]
  }
}

Or via pnpm dlx (without global install):

{
  "axiom-wiki": {
    "command": "pnpm",
    "args": ["dlx", "axiom-wiki", "mcp"]
  }
}

Now your AI assistant can read pages, search concepts, log decisions, and update wiki pages in real time while you write code!

Wiki Directory Structure

When scoped to a project (Local Wiki), everything lives in an isolated axiom/ directory. For global personal knowledge, files reside in ~/axiom/.

axiom/
├── config.json              # Local configuration (provider, model, paths, embeddings)
├── state.json               # Compilation state (SHA-256 hashes, source-to-page mappings)
├── map-state.json           # Autowiki & codebase sync tracker (git commit hashes)
├── search.index             # Orama hybrid BM25 + vector search index
├── lock                     # Transient PID lock preventing concurrent writes
├── raw/                     # Ingestion dropzone (PDF, MD, DOCX, CSV, HTML, Images)
│   ├── .axiomignore         # File ignore patterns (respects gitignore syntax)
│   └── assets/
└── wiki/                    # The compiled Markdown knowledge base
    ├── pages/
    │   ├── entities/        # People, organizations, repos, tools, services
    │   ├── concepts/        # Core ideas, architectural patterns, theories
    │   ├── sources/         # One structured summary page per ingested source
    │   └── analyses/        # Syntheses, comparisons, historical answers
    ├── index.md             # Categorized catalog of all wiki pages
    ├── moc.md               # Map of Content: auto-grouped by tags
    ├── log.md               # Append-only chronological audit log
    ├── usage.log            # Granular token consumption and cost tracking
    └── schema.md            # Wiki conventions and frontmatter schema

Anatomy of a Compiled Wiki Page

Every page generated or maintained by Axiom follows a strict YAML frontmatter convention with bidirectional wiki-links and paragraph-level citations:

---
title: "Distributed Consensus"
summary: "Protocols enabling distributed nodes to agree on a shared state."
tags: [systems, distributed-computing, consensus]
category: concepts
sources: ["raft-paper.pdf", "paxos-simple.md"]
updatedAt: "2026-04-12"
---

Distributed consensus algorithms ensure fault-tolerant state machine replication
across a cluster of unreliable machines. ^[raft-paper.pdf#p. 3 | grade: data]

Unlike [[entities/paxos]], [[concepts/raft]] decomposes consensus into leader election,
log replication, and safety guarantees to enhance understandability. ^[raft-paper.pdf#p. 7]

## Related Concepts
- [[concepts/byzantine-fault-tolerance]]
- [[entities/etcd]]

Installation Options

Package Managers

# npm
npm install -g axiom-wiki

# pnpm
pnpm add -g axiom-wiki

# yarn
yarn global add axiom-wiki

Docker

Run Axiom Wiki in any environment with Docker:

docker run -it -v $(pwd):/wiki axiomwiki/axiom-wiki init

From Source

git clone https://github.com/abubakarsiddik31/axiom-wiki.git
cd axiom-wiki
pnpm install
pnpm build
pnpm link --global

Community & Sponsoring

Axiom Wiki is free and open source software under the Elastic License 2.0 (ELv2). If Axiom saves you time or empowers your knowledge workflow, consider supporting ongoing development:

Contributing

Contributions of all forms are warmly welcome! Please check out CONTRIBUTING.md for local development setup, coding guidelines, and pull request workflows.