# nebu-ctx — Public MCP Guidance for Pi
nebu-ctx is installed as a Pi Package with first-class MCP support. User-facing guidance should recommend only the public 4-tool MCP surface: `ctx_read`, `ctx_search`, `ctx_tree`, and `ctx`.
## Public MCP Surface
- `ctx_read(target="file"|"files"|"symbol"|"outline"|"archive", ...)`
- `ctx_search(mode="regex"|"semantic", ...)`
- `ctx_tree(path, depth)`
- `ctx(domain="memory"|"context"|"graph"|"analytics"|"agents"|"inspect", action="...")`
## Guidance Rules
- Prefer the 4 public tools above in all visible instructions and examples.
- Do not recommend direct private `ctx_*` tool names unless you are explicitly documenting internal implementation details.
- Use native edit/write/delete tools for mutations; nebu-ctx's public surface is read/search/tree/ctx.
- Use native shell commands directly; the nebu-ctx shell hook compresses output automatically. If shell output ever misbehaves, retry once, then use supported raw mode or the repo-built nebu-ctx client and file/update an issue instead of falling back to a public shell wrapper tool.
## Public Examples
```text
ctx_read(target="file", path="src/main.rs")
ctx_read(target="symbol", name="main", file="src/main.rs")
ctx_search(mode="regex", pattern="pub fn", path="src/")
ctx_search(mode="semantic", query="session state persistence", path="src/")
ctx_tree(".", 2)
ctx(domain="memory", action="recall", query="session state decisions")
```
## Memory policy
- Use `ctx(domain="memory", action="save"|"recall")` for task state, findings, and decisions that should survive across chats.
- Use `ctx(domain="memory", action="store")` for durable project facts.
- The stop/compact hooks already persist session state into the nebu-ctx server; rely on that instead of chat history for reusable memory.
- If a public nebu-ctx tool fails reproducibly, retry once if it may be environmental. If it still fails, do not bypass to the native equivalent. Use supported raw mode or the repo-built nebu-ctx client, then create a GitHub issue in `MarkBovee/nebu-ctx` with repro, expected vs actual, shell/platform, and the failing tool call. Prefer `gh issue create --repo MarkBovee/nebu-ctx ...`; fall back to `nebu-ctx report-issue` if needed.
## No manual prefixing needed
The Pi extension handles routing automatically. Use the public nebu-ctx surface directly in guidance and examples:
```text
ctx_read(target="file", path="src/main.rs")
ctx_search(mode="regex", pattern="pub fn", path="src/")
ctx_tree(".", 2)
ctx(domain="memory", action="recall", query="session state decisions")
```
## Checking status
Use `/nebu-ctx` in Pi to verify which binary is active and see MCP bridge status.
## Dashboard
Use the NebuCtx server-hosted dashboard for real-time token savings, cost, and heatmap views.