agentsview-usage

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:

1. Always set --limit/limit on search_sessions, list_sessions, and search_content calls — do not request the default/max unless you need breadth.
2. Always paginate get_messages. Never fetch a whole transcript in one call; use --around/--before/--after or --from windows.
3. Prefer get_session_overview or search_content snippets over full transcript dumps. Only call get_messages when exact wording matters.
4. 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.
5. 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

• docs/guides/using-agentsview.md — setup instructions, opt-out, graceful degradation
• references/tool-reference.md — full MCP tool purposes, 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/personal-kb-usage/SKILL.md — sibling skill for cross-project personal knowledge recall (notes/decisions, not session transcripts)