![Python](https://img.shields.io/badge/python-3.10%2B-blue) ![MCP](https://img.shields.io/badge/protocol-MCP-orange) ![License](https://img.shields.io/badge/license-MIT-green)

# 🧠 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
```bash
git clone https://github.com/time-scout/autowiki-agent.git
cd autowiki-agent
pip install -e .
```

### 2. Configure
```bash
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:
```json
{
  "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](docs/00-PROBLEM-STATEMENT.md)
- [01: Provenance & Traceability](docs/01-PROVENANCE-AND-TRACEABILITY.md)
- [02: Conflict Resolution](docs/02-CONFLICT-RESOLUTION.md)
- [03: Concurrency & Control](docs/03-CONCURRENCY-AND-CONTROL.md)

---

## 🆚 v1 vs v2 (Migration Note)

This is **v2.0**. The original v1 release is preserved at [`time-scout/autowiki-daemon`](https://github.com/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.