Personal KB Usage

Query the user's personal knowledge base effectively, interpret results accurately, and stay within token budgets.

Overview

The personal-kb MCP server exposes the user's cross-project personal knowledge base as a pre-built knowledge graph stored at $AGENT_FLOW_PERSONAL_KB_PATH/graphify-out/graph.json. This is a graph built by the user from their own notes, journals, decision records, or any other personal documents — outside of any single project directory.

Owner: Riko (Explorer Agent) — Riko is the primary personal-kb query agent and owns interpretation of results. Consumers: Senku (Planner Agent), Lawliet (Reviewer Agent) — both may consult the personal KB during planning and review to surface cross-project decisions and patterns. Out of scope: Loid (Executor) and Alphonse (Verifier) do NOT have personal-kb access by design. This preserves the one-writer invariant and keeps write/verify agents focused on project artifacts.

All 7 tools are accessed via the MCP prefix mcp__personal-kb__*. See references/tool-reference.md for full signatures.

Contrast with graphify-usage:

• graphify-usage — queries the current project's graph at graphify-out/graph.json (relative to project root). Use for structural questions about THIS codebase.
• personal-kb-usage — queries the user's personal graph at an absolute path outside the project. Use for cross-project recall: prior decisions, anti-patterns encountered before, personal preferences, notes from past work.

When to Query the Personal KB vs. Project Graph vs. Grep

Rule of thumb: Personal KB is for memory across sessions and projects. Project graph is for structure within this session's codebase. Grep/Read is for current file content.

Tool Decision Table

Choose the right tool for the question type. See references/query-patterns.md for detailed decision sequences.

Token Hygiene

Hard rules for staying within context budget:

1. Always set top_k / top_n when available. Default god_nodes returns 10 nodes — only request more if explicitly needed.
2. Set token_budget on query_graph calls. The default is 2000 tokens; lower it (e.g., 500) for quick orientation queries.
3. Set depth conservatively. Default depth is 3; start at 1-2 for narrow questions, increase only if the result is insufficient.
4. Do NOT paste raw subgraph JSON downstream into task prompts or summaries. Extract only node IDs, labels, and source_location fields.
5. Summarize before handing off. Convert graph results to bullet lists of label → source_location pairs. Downstream agents (Senku, Lawliet) need names and file paths, not raw graph output.
6. Chain calls, don't parallelize blindly. Run graph_stats first, then decide if god_nodes is needed. Avoid firing all 7 tools simultaneously.

Result Interpretation

How to read and trust what the personal KB returns:

Cite source_location fields with ABSOLUTE paths

Every node in the personal KB graph carries a source_location field (file path, sometimes line range). Because the personal KB lives outside the current project root, always report these as absolute paths:

Node: AuthDecision2025
source_location: /Users/you/personal/knowledge-base/decisions/auth-patterns.md:42

Never truncate these to relative paths — downstream agents working in a different project directory cannot resolve relative paths pointing into the personal KB.

Surface confidence tags

The graph annotates edges with confidence labels:

When an edge is INFERRED or AMBIGUOUS, note this explicitly in your summary.

Personal KB vs. project docs

The personal KB reflects the user's personal notes and past decisions, not authoritative project documentation. When personal KB content conflicts with current project docs:

• Project docs take precedence for THIS project's requirements.
• Personal KB is a useful prior but not a mandate.
• Note conflicts explicitly so Senku or Lawliet can resolve them.

Trust-but-verify for recently updated notes

The personal KB graph is built once (at the user's last /graphify run on their KB) and is not updated during a session. If the user has recently added notes, those may not be indexed yet.

What NOT to Do

• Do not paste personal KB content into commit messages, PR descriptions, or other public artifacts — user notes may contain private context or personal opinions not intended for external audiences.
• Do not assume the personal KB is always authoritative over project docs — personal priors should inform, not override, current requirements.
• Do not skip the project graph query just because the personal KB has similar content — the project graph reflects THIS codebase's actual structure; personal KB reflects past experience that may not apply.
• Do not query the personal KB on freshly edited personal notes expecting current content — the graph is a snapshot.
• Do not set depth > 4 without a specific reason — output will overflow context.
• Do not pass raw graph JSON blobs in task descriptions or summaries to other agents.
• Do not report INFERRED edges as facts — always surface the confidence tag.
• Do not skip source_location citations — every claimed relationship needs a file anchor (absolute path).

Cross-References

• docs/guides/using-personal-kb.md — setup instructions, env var contract, verification steps
• references/tool-reference.md — full MCP tool signatures, parameters, cost profiles
• references/query-patterns.md — decision table mapping question types to tool sequences
• examples/worked-queries.md — end-to-end query scenarios with expected result shapes
• skills/graphify-usage/SKILL.md — sibling skill for querying the current project's graph