# local-wiki

Local-first agent wiki with **caller-side AI conflict resolution**. Stores knowledge as plain Markdown on your local filesystem, safe for multi-profile / multi-session concurrent writes via a **pending-queue commit model** — no torn writes, no silent overwrites.

Built as a standard MCP server, so it works with **any MCP client** (Hermes, Claude, Cursor, Codex, OpenCode...). Same code on any machine: `pip install local-wiki` or `uvx local-wiki`.

**Version 1.0.0** — production release. Runs either from PyPI (`uvx local-wiki`) or as a standalone executable (see [Executable release](#executable-release)).

## Why

- Skills should hold *experience* (how); **knowledge** (what) belongs in a wiki — this is the knowledge store for that.
- Naive file writes / single-writer tools have **no concurrency control** → multi-agent writes corrupt pages.
- This project fixes it with a **pending queue**: writes are staged (one file per draft in `pending/`), a single committer serializes them under an OS lock, and conflicts are resolved **by the caller (the agent) in its own conversation** — the server itself never calls an LLM.

## Design: AI resolution lives in the caller's conversation

The committer is intentionally **dumb and deterministic** (lock → hash check → atomic write → index update). It does **not** call any LLM:

1. `wiki_add` creates new pages directly (target missing) or stages a draft into `pending/<id>.json` (recording the base-hash of the version the writer read).
2. `wiki_commit` drains the queue under a single `LockFileEx`/`flock` lock (FIFO by file mtime).
   - **No drift** → commit directly.
   - **Drift** (someone else committed meanwhile) → write a conflict record `pending/<id>.conflict.json` (current + draft full text), keep the draft queued.
3. The caller sees the conflict (`wiki_conflicts` returns both versions), **merges them in its own conversation** (the agent is the AI), and submits the result:
   - `wiki_resolve(conflict_id, side='merged', merged_content=...)` → apply your merge.
   - or `side='draft'` / `side='current'`.
4. Resolution removes the draft from the queue; `wiki_commit` can then drain the rest.

**Result:** zero LLM/key dependencies in the server, fully offline, and semantic merge quality comes from the caller's model — not from a hardcoded prompt.

## Install

```bash
pip install local-wiki          # or
uvx local-wiki --help           # runs the latest PyPI release
```

## Run (MCP server)

### stdio (default)

```bash
local-wiki --wiki-root <dir>
```

### HTTP (Streamable)

```bash
local-wiki --wiki-root <dir> --host 127.0.0.1 --port 8000
```

### Standalone executable (no Python required)

```bash
local-wiki.exe --wiki-root <dir>
```

## Wire into clients

### Hermes (`config.yaml`) — standard PyPI run, no local source build

```yaml
mcp_servers:
  wiki:
    command: uvx
    args: ["local-wiki", "--wiki-root", "C:/Users/Administrator/AppData/Local/hermes/wiki"]
```

> Hermes historically used `uvx --from <local-src-path>` (build from source each launch). Since 1.0.0 the canonical setup is the PyPI package above; the standalone `.exe` can be pointed to directly with `command: <path>/local-wiki.exe`. The local-wiki **dev** setup in this repo (local-wiki-dev profile) instead runs the editable venv via `python -m mcp_server_wiki` (see "OpenCode / Hermes local-wiki-dev" above) — source edits take effect on MCP restart, no PyPI/PyInstaller needed.

### Claude Code

```bash
claude mcp add local-wiki -- uvx local-wiki --wiki-root ~/wiki
```

### OpenCode / Hermes local-wiki-dev (this repo's dev setup)

The dev wiki MCP runs from the editable venv via `python -m mcp_server_wiki` (the reload switched off the `local-wiki.exe` launcher to the source module):

```
E:/wyd_work/local-wiki/.venv/Scripts/python.exe -m mcp_server_wiki --wiki-root E:/wyd_work/local-wiki/dev-wiki
```

The venv is an editable install of this repo, so source edits take effect after restarting the MCP server process — no PyInstaller rebuild needed.

## MCP Tools (13)

| Tool | Description |
|---|---|
| `wiki_add(title, keywords=[], content="", root="")` | Unified knowledge write entry. Routes by title match → root-keyword intersection ≥5 → page-keyword intersection ≥5 → else `{error}`. New page = direct create; existing = staged to `pending`. **Replaces the old `wiki_write`.** |
| `wiki_delete(title, root="")` | Delete a page by normalized title; staged to `pending`. |
| `wiki_commit(once=False)` | Serialize pending queue → commit; on drift write conflict record, keep draft queued. |
| `wiki_conflicts()` | List open conflicts with full current+draft content for in-dialogue merge. |
| `wiki_resolve(conflict_id, side, merged_content="")` | Apply draft / keep current / apply caller's merged content. |
| `wiki_lint()` | Health check: index completeness, orphans, dead links, queue backlog, open conflicts, body length. |
| `wiki_index(profile, action="read", rel="", keywords=[])` | Maintain **root-level** keywords only. `action='update'` with `rel` omitted sets the root's category keywords; per-file keywords are no longer supported. |
| `wiki_search(query, profile="")` | Search the in-memory index by rel/title/keywords (case-insensitive). |
| `wiki_read(profile, rel)` | Read a page's full content (markdown with frontmatter). |
| `wiki_list(profile="")` | List page index entries (rel/title/updated/words/hash). |
| `wiki_create_root(key, name, workdir="", type="project", owner_profile="")` | Register a new wiki root (project shard) + its `index.json`. |
| `wiki_update_root(key, name="", workdir=None, owner_profile="", type="")` | Update a root's meta. |
| `wiki_delete_root(key, purge=False)` | Unregister a root (purge=True deletes its folder, irreversible). |

> **Note:** `wiki_write` was removed in the refactor — use `wiki_add`. `profile` (read/search/list) and `root` (write) are the same thing: the **root key** (e.g. `global`, `smart_park`).

## Storage Layout (current)

```
<wiki-root>/
├── .wiki/
│   ├── global/                    # cross-project knowledge (a normal root)
│   │   ├── <rel>.md               #   pages directly here (NO pages/ subdir)
│   │   └── index.json             #   {version, meta, keywords:[...]}
│   └── <root>/                    # one folder per registered root
│       ├── <rel>.md
│       └── index.json
└── .pending/                      # flat draft queue — one file per change
    ├── <id>.json                  #   draft record (target_path, op, content, base_hash)
    ├── <id>.conflict.json         #   conflict record (current + draft)
    └── .lock                      #   OS file lock (committer holds)
```

- Roots are registered by the existence of `.wiki/<dir>/index.json` (directory name = root key). There is **no top-level registry file**.
- `global` is just another root.
- `index.json` per root holds `{version, meta, keywords:[...]}` where `keywords` is the **root-level category list** (a top-level array). Per-page keywords are NOT stored in `index.json` — they live only in each page's frontmatter.

### Root naming — normalized to snake_case

Root folder names are normalized: camelCase, hyphens and whitespace all resolve to the same snake_case key.

- `smart-park` / `smartPark` / `SmartPark` → `smart_park`
- `wiki_create_root` accepts any spelling and stores the normalized key (must match `[a-z0-9_]+` after normalization)
- Passing an alias (e.g. `smart-park`) to read/write/search/update/delete works — it resolves to the canonical root

## Data model

### Pages

Every page is Markdown with an optional YAML frontmatter; one is auto-added if missing (title = first heading, `keywords: []`).

```markdown
---
title: Docker 使用
keywords: [特有kw]
---
<正文 body>
```

- **Keywords**: page frontmatter keywords are limited to a **count** (default 10; configurable via env `WIKI_KEYWORDS_MAX`). Root `index.json` keywords are **category** tags with no count limit. Invalid frontmatter is rejected on every write path.
- **Body length**: must be < 10 000 tokens (DeepSeek-V4 official BPE tokenizer, offline, checked by `wiki_lint`).
- **Invalid frontmatter** (starts with `---` and has a closing marker but fails YAML) is rejected on every write path.

### Write semantics (current)

- `wiki_add` on a missing target → written directly (atomic), index updated.
- `wiki_add` / `wiki_delete` on an existing target → staged into `pending/`, committed serially by `wiki_commit`.
- `wiki_add` routing when the target is ambiguous: title match → root-keyword intersection ≥5 → page-keyword intersection ≥5 → otherwise returns `{error, hint}` (not written; the caller may create a new root with `wiki_create_root`).
- **All write paths normalize content** through one validator (`_normalize_content`): frontmatter validity, keyword count/length, auto-add missing frontmatter — **including `wiki_resolve` merged/draft**, so bad content can never enter the wiki through conflict resolution.

### Concurrency

- **Cross-root**: physical sharding (`.wiki/<root>/`) — different files, no collision.
- **Same-root, multi-session**: single committer + OS file lock serializes the queue.
- **Atomic writes**: temp-file + rename — readers never see partial state.
- **Conflict**: base-hash drift → both sides exposed; caller merges in-dialogue; nothing silently dropped.
- **Delete drift**: a delete based on a stale version surfaces as a conflict (`op=delete`); `resolve(side='draft')` executes the delete, `side='current'` keeps the concurrent update.

## Executable release

Since 1.0.0 a standalone Windows executable is built with PyInstaller (no Python/uvx needed):

```bash
# from repo root
pyinstaller build/local-wiki.spec
# → dist/local-wiki.exe
```

The tokenizer asset (`src/mcp_server_wiki/assets/tokenizer.json`) is bundled into the executable, so offline token counting works in the exe too.

## Dev

```bash
pip install -e .[dev]
pytest                     # unit tests (tests/test_*.py)
```

After editing `src/`, restart the running MCP server — a running process holds the old code and will not reflect your changes.

## Companion skill

`skills/local-wiki-usage/` ships the agent skill that teaches how to read/write the wiki correctly (write routing, pending-queue workflow, conflict resolution, pitfalls). It has been updated to the current `wiki_add` / `.wiki/<root>/` API.

## License

MIT
