| name | agentsview-usage |
| description | Search prior session history to recall how similar work was handled before. Use when you want to leverage a past approach, check prior experience on a topic, answer "how was this handled before", or cross-verify current handling against precedent from earlier sessions. |
AgentsView Usage
Search prior session history effectively, interpret results accurately, and stay within token budgets.
Overview
The agentsview MCP server exposes prior AI coding agent session history (synced by the agentsview CLI into a local SQLite archive) as read-only search tools, started via agentsview mcp.
All five granted tools are accessed via the MCP prefix mcp__plugin_agent-flow_agentsview__*.
Owner: Riko (Explorer Agent) โ Riko is the primary session-history search agent and owns interpretation of results.
Consumers:
- Senku (Planner Agent) โ leverages past approaches when designing an implementation strategy: "has a similar feature been built before, and how?"
- Lawliet (Reviewer Agent) โ cross-verifies current handling against precedent: "does this change match or diverge from how similar changes were handled previously?"
Out of scope: Loid (Executor) and Alphonse (Verifier) do NOT have agentsview access by design. This preserves the write/verify separation and keeps write/verify agents focused on the current diff and verification commands, not historical recall.
When to Query Session History vs. Graph vs. Grep
| Trigger condition | Preferred approach |
|---|
| "How was a similar task handled before?" | AgentsView: search_sessions |
| "What was decided/done in a specific prior session?" | AgentsView: get_session_overview |
| "What exact messages/commands were used before?" | AgentsView: get_messages (paginated) |
| "Find prior mentions of a specific string/error/pattern" | AgentsView: search_content |
| "What sessions ran recently on this project?" | AgentsView: list_sessions |
| "What is the dependency structure of THIS project?" | Project graph (graphify-usage) |
"Find the string literal TODO: fix" in current files | Grep |
| "What does a specific config key say in THIS project?" | Read the file directly |
AgentsView is not available (agentsview: available: false in state) | Skip โ proceed without session-history search |
Rule of thumb: AgentsView is for recall of how prior work was actually done across past sessions. 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.
| Question type | Primary tool | Follow-up |
|---|
| Find past sessions on a topic | search_sessions | get_session_overview on the best match |
| Browse recent sessions (no specific topic) | list_sessions | get_session_overview on a candidate |
| Summarize one known session | get_session_overview | get_messages if exact wording is needed |
| Read exact prior messages/commands | get_messages (always limit/paginate) | โ |
| Full-text search across message/tool content | search_content | get_messages around the matched ordinal |
Note: get_usage_summary is intentionally not granted to any persona โ token/cost accounting is out of scope for session-history recall.
Token Hygiene
Hard rules for staying within context budget:
- Always set
--limit/limit on search_sessions, list_sessions, and search_content calls โ do not request the default/max unless you need breadth.
- Always paginate
get_messages. Never fetch a whole transcript in one call; use --around/--before/--after or --from windows.
- Prefer
get_session_overview or search_content snippets over full transcript dumps. Only call get_messages when exact wording matters.
- Extract session IDs and short snippets only. Do not paste raw multi-message transcripts downstream โ summarize into bullet findings with session ID + one-line takeaway.
- Chain calls, don't parallelize blindly. Run
search_sessions or search_content first, then decide if get_session_overview/get_messages is needed for the top match.
Result Interpretation
How to read and trust what AgentsView returns:
History is a prior, not a mandate
A prior session shows how something was handled โ not how it must be handled now. Requirements, codebase state, and constraints may have changed since. Always treat precedent as informative context, not binding instruction.
Flag precedent-vs-current-requirement conflicts
When a prior session's approach conflicts with the current task's explicit requirements or constraints, surface the conflict explicitly rather than silently following either one:
Precedent (session <id>, <date>): used approach X.
Current requirement: approach Y is specified.
Flagging conflict for the orchestrator/user to resolve.
Trust-but-verify
Session history reflects what happened in that session, not necessarily what was correct or still applies. Cross-check any recalled approach against the current codebase before relying on it โ a pattern that worked in a past session may since have been refactored away or found to be wrong.
What NOT to Do
- Do not treat prior handling as binding โ a past session's approach is a data point, not a requirement.
- Do not paste raw transcripts downstream โ summarize into session ID + snippet + takeaway; downstream agents need conclusions, not full logs.
- Do not substitute recall for reading current files โ always verify prior approaches still apply by reading the current codebase state.
- Do not fetch full transcripts (
get_messages without pagination) when search_sessions/get_session_overview already answers the question.
- Do not call
get_usage_summary โ it is not granted; token/cost accounting is out of scope.
Cross-References
