Wiki Find CLI — Baseline Agent Retrieval

Date: 2026-04-20 Status: approved for implementation Owner: mnemosyne

Problem

Agents currently have no fast, deterministic way to locate a wiki page by keyword. Two retrieval paths exist, both wrong for this job:

1. mnemosyne wiki query <question> — calls Ollama (gemma), synthesizes prose. Slow (seconds to minutes), token-heavy, returns narrative not paths. Designed for "answer the question" not "locate the doc."
2. mcp__aion__aion_wiki — MCP wrapper around the same Ollama path. Same cost profile.

Real incident captured during this brainstorm: a second session's agent spent 6+ minutes and 4k tokens running four wiki query calls to locate the Mastra framework decision doc. None succeeded — partly because the answer was synthesized away from the actual paths, partly because the source research doc was not ingested into the vault.

Baseline capability missing: "does a wiki page exist for X, and where is it?"

Goals

Operator requirements:

• Simple CLI command that finds a page by keyword, or fails clearly with no match
• Filesystem-deterministic — no Ollama, no LLM roundtrip
• Efficient — minimal context, minimal latency, minimal tokens
• CLI-first (fleet rule: CLI over MCP)
• No new MCP surface required

Non-goals:

• Not a semantic search. Keyword substring only.
• Not a content synthesizer. Callers Read the returned path if they want content.
• Not a replacement for wiki query — complementary primitive.

Design

Command

mnemosyne wiki find <keyword> [<keyword>...] [--cat] [--json] [--limit N]

Match Semantics

• AND across all keywords: a page must contain every keyword somewhere in its searchable surface
• Searchable surface per page: title (from frontmatter), filename, body — unioned
• Per-keyword case-insensitive substring match
• Optimization: for each page, check title+filename first for all keywords; only load body text if at least one keyword didn't match on title+filename. Keeps I/O to the minimum needed to decide.

Output — Default

Compact list, one page per line:

analyses/mastra-framework-decision-trail.md — Mastra Framework Decision Trail
hermes/hermes-mastra-changelog-analysis.md — Hermes Mastra Changelog Safety Analysis

Format: <relative-path> — <title>. Path is relative to vault root (stable across machines, operator knows the vault). Title is the page's frontmatter title field, falling back to filename stem when missing.

Flags

• --cat — dump full page content to stdout if and only if exactly one match. With 0 or 2+ matches, exit with error (no partial behavior).
• --json — machine-readable output: [{"path": ..., "title": ..., "constellation": ..., "type": ...}, ...]. Empty array on no match.
• --limit N — cap results (default 20). Prevents pathological floods.

Exit Codes

• 0 — one or more matches found, output written to stdout
• 1 — zero matches; stderr prints no wiki page matches '<keyword>[ <keyword>...]'
• 2 — --cat with wrong match count (0 or 2+); stderr explains

Scope of Search

Same surface as _list_wiki_pages() in src/mcp/aion_tools.py:132:

• Per-constellation dirs under VAULT_ROOT (atlas, hades, mnemosyne, proteus, metis, apollo, hermes, hephaistos, athena)
• analyses/ cross-cutting dir
• Not recursive — only *.md at one level deep per existing convention

VAULT_ROOT and CONSTELLATIONS imported from src/wiki/config.py — no hardcoded paths.

Implementation

Files

New: src/wiki/find.py

• find_pages(keywords: list[str], limit: int = 20) -> list[dict] — pure function, returns matches
• Handles vault scan, AND-substring filter, title extraction from frontmatter
• Reuses _list_wiki_pages pattern but inlined + extended with body scan

New: tests/test_wiki_find.py

• Test fixtures with synthetic vault structure
• Covers: title match, filename match, body match, AND semantics, zero-match fail, limit cap, frontmatter title fallback

Modified: src/mnemosyne.py

• Add find subcommand to existing wiki subparser
• --cat, --json, --limit flags wired
• Exit code handling per spec

Modified: .claude/context/commands.md

• Document wiki find with example

Modified: CLAUDE.md (wiki section) — add wiki find as primary retrieval primitive; wiki query demoted to "when you need synthesis, not location"

Acceptance Criteria

1. mnemosyne wiki find mastra returns existing matches in under 500ms on current vault (94 pages)
2. mnemosyne wiki find nonexistent exits 1, stderr has error message, stdout empty
3. mnemosyne wiki find mastra slack applies AND — fewer or equal results than single-keyword
4. mnemosyne wiki find <unique-keyword> --cat dumps full matching page body
5. mnemosyne wiki find mastra --cat (multiple matches) exits 2 with helpful stderr
6. mnemosyne wiki find mastra --json produces valid JSON parseable by agents
7. All existing tests still pass; new find tests >= 6 cases, all green
8. Separately: Source research doc agent-ecosystem-report-2026-03.md (from archived mimir-agent repo) ingested into Aion vault under analyses/ with constellation owner = atlas. Verifies the real-world use case that triggered this design.

Out of Scope

• MCP tool wrapper for find — can be added later if CLI-over-MCP rule is relaxed for this specific case, but not now
• SQLite FTS5 cache — YAGNI at 94 pages; revisit at 1000+
• Regex matching — keep to substring; regex becomes a footgun in agent contexts
• Fuzzy/Levenshtein matching — deterministic only
• Ranking/scoring — wiki query already does that via _rank_pages_by_relevance
• Recursive subdirectory scan — current vault is flat; extending would need schema update first

Risks & Mitigations

• Vault path drift: mitigated by importing from src/wiki/config.py
• Body scan latency growth: 94 pages today. Implementation checks title/filename first to short-circuit. If vault hits 1000+ pages, revisit with FTS5 cache (future spec).
• Frontmatter-less pages: fallback to filename stem as title. Test covers this.
• Agents still defaulting to wiki query: CLAUDE.md update + mnemosyne-reflex skill nudge lead agents to find first. Not enforced by hook (too brittle), just documented as primary.

References

• Internal helper: src/mcp/aion_tools.py:132 (_list_wiki_pages)
• Keyword ranking precedent: src/wiki/engine.py:237-299 (different primitive — scored synthesis)
• Deregistration backlog: backlog/mcp--deregister-legacy-mnemosyne-tools.done.md
• Fleet rule enforcement: ~/.claude/rules/05-skill-enforcement.md (CLI-over-MCP)
• Vault schema: $AION_VAULT/SCHEMA.md