🧠 AutoWiki Agent: The Autonomous Knowledge Base Compiler

Stop letting LLMs hallucinate over your notes.

AutoWiki Agent is a deterministic Model Context Protocol (MCP) server that compiles any LLM-readable text — transcripts, articles, contracts, notes — into a strict, verifiable, graph-based knowledge base.

No silent overwrites. No hallucinated facts. No lost sources. Just pure, traceable knowledge evolution.

v2.0 — Autonomous Architecture. Unlike v1, the server itself drives the LLM through deterministic chunking and parallel extraction of 6 epistemology primitives. The client agent is reduced to a thin pipe.

---

🔥 The Problem With AI Agents Editing Your Wiki

When you ask an AI to "update my wiki," it usually fails:

• ❌ Silent Overwrites: It deletes old (but vital) facts to make room for new ones.
• ❌ Hallucinations: It bridges knowledge gaps by inventing compromises.
• ❌ Lost Sources: You have no idea which PDF or web search a specific sentence came from.
• ❌ Schema Drift: Every agent invents its own entity shape; the wiki becomes a junk drawer.

AutoWiki Agent fixes all of this.

---

🛡️ Core Features

1. Bottom-Up Epistemology (6 Primitives, Not Categories)

AutoWiki rejects hard-coded "Client" or "Pain Point" types. Instead, every chunk is parsed into 6 universal epistemology primitives:

Primitive	Schema	What It Captures
Document DNA	DocumentDNA	Format, primary intent, tone (one-shot per file)
Identifiers	UniversalIdentifier	Names, jargon, entities (with normalization)
Quantifiers	UniversalQuantifier	Numbers, dates, metrics, units
Relations	UniversalRelation	Subject → action → target graph edges
Directives	UniversalDirective	Tasks, promises, obligations, warnings
Unknowns	UniversalUnknown	Explicit knowledge gaps and open questions

2. Server-Driven LLM Calls

The server calls the LLM directly via HTTP. The client agent does not need to perform extraction itself. This means:

• Deterministic chunking via tiktoken (1000 tokens / 150 overlap)
• Parallel sampling (5 concurrent requests per chunk)
• Strict Pydantic schema validation with automatic retry
• Pagination (start_chunk / max_chunks) to avoid timeouts

3. Iron Standard Source Protocol

Every fact in /wiki is anchored to a Source Passport in /inbox. No source — no fact.

4. Knowledge Evolution Protocol

Facts are never deleted. Updates are documented inline (*(Evolution: previously described as...)*). Contradictions are flagged with #NEEDS_HUMAN_RESOLUTION, never silently resolved.

5. Gatekeeper Filter

Only entities explicitly extracted from a chunk may "own" facts in that chunk. Anything else is bucketed into a Document_* container. Prevents cross-contamination of unrelated entities.

6. Git-Backed Audit Trail

Every semantic update is committed to a local Git repository. Full history, no overwrites.

7. MCP Native

Drop-in integration with Claude Desktop, Cursor, Gemini CLI, Windsurf, Roo Code, and any MCP-compatible client.

---

🚀 Quickstart

1. Install

git clone https://github.com/time-scout/autowiki-agent.git
cd autowiki-agent
pip install -e .

2. Configure

cp .env.example .env
# Edit .env and set LLM_API_KEY, LLM_BASE_URL, LLM_MODEL

The server expects an OpenAI-compatible chat completions endpoint.

3. Connect your MCP client

Add this to Claude Desktop, Cursor, Gemini CLI, Windsurf, or Roo Code:

{
  "mcpServers": {
    "autowiki": {
      "command": "autowiki",
      "args": ["start"]
    }
  }
}

4. Initialize and use

Talk to your AI client:

"Initialize my workspace at ~/Desktop/MyBrain. Then process everything in /inbox."

Watch what happens:

1. AutoWiki sets up /inbox, /wiki, /archive, /.autowiki.
2. Drop a file into /inbox (any text/markdown/JSON).
3. Call autowiki_ingest_document — the server chunks, calls the LLM 5x in parallel per chunk, validates against Pydantic schemas, retries on failure.
4. Knowledge graph is committed to /wiki and Git.

---

📁 Workspace Layout

<workspace>/
├── inbox/        # Drop raw sources here (text, md, json)
├── wiki/         # Compiled knowledge base (one .md per entity)
├── archive/      # Processed sources (auto-moved)
└── .autowiki/    # Internal SQLite state

---

🛠 MCP Tools Exposed

Tool	Purpose
check_autowiki_status	Returns init status (call this first)
autowiki_onboarding	Initializes the workspace
autowiki_ingest_document	Chunks + LLM extraction + commit (paginated)
format_filename	Generates Iron Standard filename
read_inbox	Lists files in /inbox
get_entity_knowledge	Reads entity from /wiki
commit_updates	Writes facts to /wiki (manual use)

---

📜 Technical Documentation (ADR)

Detailed architectural decisions live in docs/:

• 00: Problem Statement
• 01: Provenance & Traceability
• 02: Conflict Resolution
• 03: Concurrency & Control

---

🆚 v1 vs v2 (Migration Note)

This is v2.0. The original v1 release is preserved at time-scout/autowiki-daemon for historical reference.

Aspect	v1 (Daemon)	v2 (Agent)
Chunking	Done by the LLM agent	Deterministic tiktoken 1000/150
Entity extraction	Agent-driven, ad-hoc	Server-driven, 6 fixed primitives
LLM calls	~2 (extract, compare)	5 parallel per chunk + DNA per file
Schema	2 Pydantic models	6 Pydantic models
Concurrency	Single-writer	5 concurrent LLM calls per chunk
Pagination	None	start_chunk / max_chunks
Entity filter	None	Gatekeeper: only chunk-local entities
Working language	English	Ukrainian (UI/logs), English (prompts), source-locale (facts)

---

⚖️ License

Distributed under the MIT License. See LICENSE for more information.