coco-research/coco/brain-wiki

/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.

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.

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

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] ``

1. 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 ```

1. 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}" ```

1. 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] ```

1. 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 ```

1. 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" ``

1. 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] ```

1. 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

1. On skip: record the skip decision (do not re-propose the same pair for 30 days).

1. 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 ``

1. 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 ```

1. If claude binary not found, show the error from _find_claude_binary() with install instructions.

To uninstall:

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:

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).