brain:wiki · git:20260914.e75f220 · 2026-09-14 · sha256 345a61057f696c5c
brain:wiki git:20260914.e75f220A
Immutable. This exact content is served forever at /api/v1/blob/345a61057f696c5c.
---
name: brain:wiki
description: "Use when the user asks for a knowledge article, wiki page, or entity summary from the brain, or wants to search, list, or review merges across brain DB articles. Generates Wikipedia-style articles from entities, decisions, and emails."
---
# /brain-wiki — CoCo Knowledge Articles
Browse, search, and generate Wikipedia-quality articles about people, systems, teams,
and org units across all CoCo brain DB projects.
Articles are auto-generated from the brain DB by the daily knowledge engine cron
(`~/.coco/knowledge/cron.py`). Each article synthesizes all evidence available about
an entity — decisions, events, relationships, tasks — into a structured, versioned
knowledge artifact.
## Prerequisites
Articles live in the external knowledge engine at `~/.coco/knowledge/` (`cron.py` and
`knowledge.db`), which does not ship in this repo. Wire this skill with
`bash adapters/<your-ide>/install.sh --systems brain` and install the engine itself
before using anything below.
---
## Commands
### `/brain-wiki [entity]` — Show article (or list all)
**With entity name:** Look up and display a knowledge article.
```bash
python3 ~/.claude/skills/brain/scripts/brain/brain_cli.py wiki --name "{entity}"
```
Display format:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
{Title} [{type}]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Infobox: Projects: {list} | Role: {role} | Team: {team}
{Summary paragraph}
## Role
{content}
## Relationships
{content}
## Timeline
{content}
## Decisions
{content}
## Open Questions
{content}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Generated: {date} · Confidence: {0-100}% · Sources: N chunks
GID: {uuid} · v{version}
```
If article not found → run wiki-search with the entity name as query and show top 3 candidates:
```
No article found for "{entity}". Did you mean:
1. {title} ({confidence}%) — /brain-wiki {gid}
2. {title} ({confidence}%)
3. {title} ({confidence}%)
```
Warnings to show inline:
- If confidence < 30%: `⚠ Low confidence — this article needs more source data. Run /brain-update after adding more context.`
- If pending merge proposals exist for this entity: `ℹ Possible duplicate: matches "{other_name}" ({similarity}%) — run /brain-wiki review-merges to resolve`
**Without entity name:** List all available articles.
```bash
python3 ~/.claude/skills/brain/scripts/brain/brain_cli.py wiki-search "*" --limit 50
```
Display as table:
```
KNOWLEDGE BASE · N articles
═══════════════════════════════════════════════════════════
Name Type Confidence Updated
─────────────────────────────────────────────────────────
Alice Example person 87% 2h ago
VendorPortal system 91% yesterday
DataPipeline system 76% 2d ago
Platform Team team 82% 2d ago
...
```
---
### `/brain-wiki search <query>` — Unified FTS5 + semantic search
```bash
python3 ~/.claude/skills/brain/scripts/brain/brain_cli.py wiki-search "{query}"
```
Runs both FTS5 keyword search and MemPalace semantic search, merges via RRF.
Display format:
```
SEARCH: "{query}" · N results · FTS5 + semantic
══════════════════════════════════════════════════════════════
# Name Type Confidence Projects Updated
─────────────────────────────────────────────────────────────────
1 {title} {type} {conf}% {projects} {time}
2 ...
Run /brain-wiki {name} to read the full article.
```
If 0 results:
```
No articles found for "{query}".
Entity may not be in any brain DB yet, or articles haven't been generated.
Run: /brain-wiki generate to generate articles for all brain entities.
```
---
### `/brain-wiki generate [project]` — Generate / refresh articles
Generates or refreshes knowledge articles from brain DB evidence.
**Procedure:**
1. If a project is specified, confirm scope:
```
Generate articles for project "{project}"?
This will use Claude API (estimated $0.XX for N entities).
[Y/n]
```
If no project specified, confirm all:
```
Generate articles for ALL registered projects?
Registered: {slug1}, {slug2}, ... (N projects, ~N entities)
Estimated cost: $0.XX · Estimated time: N minutes
[Y/n]
```
2. On confirmation, run:
```bash
# Single project
python3 ~/.coco/knowledge/cron.py --run --project {slug} --phases 2,3,5
# All projects
python3 ~/.coco/knowledge/cron.py --run --phases 2,3,5
```
3. Show phase-by-phase progress as output streams:
```
Phase 2: Harvesting evidence...
✓ {project}: N entities, N evidence chunks
Phase 3: Generating articles...
✓ Generated: Alice Example (confidence: 87%)
✓ Generated: VendorPortal (confidence: 91%)
~ Skipped: 3 entities (unchanged)
Phase 5: Indexing...
✓ N articles indexed (FTS5)
─────────────────────────────────────────
KNOWLEDGE ENGINE
================
Articles generated: N new, N updated
FTS5 indexed: N
Estimated cost: $0.XXX
Articles written to: ~/.coco/knowledge/articles/
Search with: /brain-wiki search "{project}"
```
4. Add `--force` flag to regenerate all articles regardless of staleness.
---
### `/brain-wiki people` — Show cross-project people graph
Show all person-type articles and cross-project relationship statistics.
**Procedure:**
1. Query knowledge.db directly (do NOT invoke cron --dry-run):
```python
import sys, sqlite3, json
sys.path.insert(0, str(Path("~/.coco/knowledge").expanduser()))
from schema import KNOWLEDGE_DB_PATH
conn = sqlite3.connect(KNOWLEDGE_DB_PATH)
# People articles
people = conn.execute("""
SELECT ge.canonical_name, ge.aliases_json, ge.merged_from_json,
a.confidence, a.generated_at, a.version
FROM global_entities ge
LEFT JOIN articles a ON a.gid = ge.gid
WHERE ge.type = 'person'
ORDER BY a.confidence DESC NULLS LAST
""").fetchall()
# Pending merges
merges = conn.execute("""
SELECT COUNT(*) FROM cross_project_connections
WHERE connection_type = 'proposed_merge'
""").fetchone()[0]
# Works-with edges
edges = conn.execute("""
SELECT COUNT(*) FROM cross_project_connections
WHERE connection_type = 'works_with'
""").fetchone()[0]
```
2. Display:
```
PEOPLE GRAPH · N people across N projects
════════════════════════════════════════════════════════
Name Projects Confidence Updated
─────────────────────────────────────────────────────────
Alice Example my-project 87% 2h ago
...
Works-with relationships: N edges inferred
Pending merge proposals: N — run /brain-wiki review-merges to resolve
```
3. If no people articles yet:
```
No people articles found. Run /brain-wiki generate to build the knowledge base.
```
---
### `/brain-wiki review-merges` — Review and approve entity merge proposals
Interactively review merge proposals (entities that may be duplicates).
**Procedure:**
1. List pending merges directly from `~/.coco/knowledge/knowledge.db` (there is no
`wiki --list-merges` subcommand):
```bash
sqlite3 ~/.coco/knowledge/knowledge.db ".tables"
```
2. For each pending merge, show both entities' summaries side by side:
```
MERGE PROPOSAL (similarity: 92%)
══════════════════════════════════════════════════════════
KEEP candidate A: KEEP candidate B:
───────────────────────────── ─────────────────────────
Name: Alice Example Name: Alice Examplé
GID: {uuid-a} GID: {uuid-b}
Projects: project-a, project-b Projects: vendor-integration
Summary A: {2-3 sentences} Summary B: {2-3 sentences}
══════════════════════════════════════════════════════════
Action: [A=keep A | B=keep B | s=skip | q=quit]
```
3. On approval, apply the merge directly in `~/.coco/knowledge/knowledge.db` (there is no
CLI subcommand for it), which:
- Reassigns all articles from gid_remove → gid_keep
- Adds the removed entity's name to gid_keep's aliases
- Deletes gid_remove from global_entities
- Uses delete-then-reinsert for articles_fts (not UPDATE, which fails on virtual tables):
`DELETE FROM articles_fts WHERE gid=gid_remove` then re-INSERT with gid_keep
4. On skip: record the skip decision (do not re-propose the same pair for 30 days).
5. Show completion summary:
```
MERGE REVIEW COMPLETE
=====================
Approved: N merges
Skipped: N pairs
Remaining: N pending
```
---
### `/brain-wiki install-cron` — Set up daily improvement cron
Install the daily knowledge engine job via macOS launchd.
**Procedure:**
1. Check that claude binary is resolvable first (the installer validates this):
```bash
python3 ~/.coco/knowledge/cron.py --install
```
2. Show confirmation:
```
KNOWLEDGE CRON INSTALLED
========================
Schedule: Daily at 02:00
Claude binary: {resolved path}
Python binary: {resolved path}
Plist: ~/Library/LaunchAgents/com.coco.knowledge-cron.plist
Log: ~/.coco/knowledge/cron.log
To uninstall: /brain-wiki uninstall-cron
To test now: python3 ~/.coco/knowledge/cron.py --run --dry-run
```
3. If claude binary not found, show the error from `_find_claude_binary()` with install instructions.
To uninstall:
```bash
python3 ~/.coco/knowledge/cron.py --uninstall
```
---
### `/brain-wiki stats` — Show knowledge engine statistics
Display current state of the knowledge engine without running any generation.
**Procedure:**
Query knowledge.db directly:
```python
import sqlite3, json
from pathlib import Path
conn = sqlite3.connect(Path("~/.coco/knowledge/knowledge.db").expanduser())
stats = {
"entities": conn.execute("SELECT COUNT(*) FROM global_entities").fetchone()[0],
"articles": conn.execute("SELECT COUNT(*) FROM articles").fetchone()[0],
"fts_rows": conn.execute("SELECT COUNT(*) FROM articles_fts").fetchone()[0],
"pending_merges": conn.execute(
"SELECT COUNT(*) FROM cross_project_connections WHERE connection_type='proposed_merge'"
).fetchone()[0],
"works_with": conn.execute(
"SELECT COUNT(*) FROM cross_project_connections WHERE connection_type='works_with'"
).fetchone()[0],
"last_gen": conn.execute(
"SELECT MAX(run_at) FROM generation_log WHERE phase='3_generate' AND status='ok'"
).fetchone()[0],
"last_sync": conn.execute(
"SELECT MAX(run_at) FROM generation_log WHERE phase='6_sync' AND status='ok'"
).fetchone()[0],
"by_type": conn.execute(
"SELECT type, COUNT(*) FROM global_entities GROUP BY type"
).fetchall(),
}
```
Display format:
```
KNOWLEDGE ENGINE STATS
══════════════════════════════════════════════════
Entities: N (person: N, system: N, team: N ...)
Articles: N (FTS5 indexed: N)
Relationships: N works_with edges
Pending merges: N proposals awaiting review
Last generation: {time ago}
Last MemPalace sync: {time ago}
Articles directory: ~/.coco/knowledge/articles/ (N files)
DB size: {KB/MB}
══════════════════════════════════════════════════
Commands: /brain-wiki generate · /brain-wiki search · /brain-wiki review-merges
```
If knowledge.db does not exist:
```
Knowledge engine not initialized.
Run /brain-wiki generate to bootstrap, or /brain-wiki install-cron for daily automation.
```
---
## Implementation Notes
- **FTS5 scoring:** BM25 rank in SQLite FTS5 is negative (more negative = better match).
Score normalization: `score = 1.0 / (1.0 + abs(rank))` — higher score = more relevant.
- **body_json → FTS5 text:** FTS5 indexes plain text, not raw JSON. The engine extracts
`section["content"]` from each section in `body_json` before inserting into `articles_fts`.
- **articles_fts updates:** Virtual tables cannot be bulk-UPDATEd. Always use
DELETE WHERE gid=? then re-INSERT for any gid change (e.g., merge approvals).
- **Project registration:** Before the cron can harvest a project, it must be registered:
```python
from engine import KnowledgeEngine
engine = KnowledgeEngine()
engine.register_project(...) # pass the project slug and path to project_brain.db
```
brain-init Step 8 calls this automatically.
- **Kill switch:** If `~/.coco/disabled` exists, all brain-wiki commands should exit silently
(consistent with CoCo kill switch convention).