MCP SERVER
Session memory that persists across conversations.
| Tool | Purpose | Returns |
|---|---|---|
| learnings | Record, query, and delete qualitative insights — corrections, preferences, workflow discoveries, terminology. Three actions in one tool: record persists, query searches, delete prunes. Duplicate detection prevents the same insight from being stored twice. | Learning object with ID, category, content, session slug, timestamp. Query includes category breakdown stats. |
| trends | Cross-session analytics over time. Daily spend, token usage, tool call volume, failure rates. Identifies the most expensive sessions and spending patterns across configurable windows. | Daily summaries, cost totals, cache hit rates, top N sessions ranked by cost with duration and tool counts. |
| tools | Per-tool call count, failure rate, average duration, and sample errors. Filters by session, minimum calls, or failures only. Bash gets special treatment — command prefix breakdown shows which shell commands are actually being run. | Tool summaries sorted by calls/failures/duration. Error categories with counts, sample error messages, bash command prefixes. |
| servers | Groups tool calls by MCP server. Shows call volume, failure rates, unique tools used, and total duration. Compares against a known server list to surface unused servers wasting context window on tool descriptions. | Server summaries with tool inventories. Unused server list for identifying dead weight in the config. |
| stats | Deep dive into a single session. Lookup by session ID, slug, or omit for the most recent. Covers cost, tokens, tool calls, duration, models used, and file change summary. | Full session stats object — cost breakdown, token counts, model usage, tool call totals, file changes. |
| list | Browse sessions with date range filtering. Sort by date, cost, duration, or tool count. Optional full stats per session for deeper analysis at the cost of scan time. | Session list with metadata. Optional inline stats. Count, total in range, and date boundaries. |
Most session context evaporates when the conversation ends. Grounder's learnings system captures durable insights — corrections ("use bun, not npm"), preferences ("design discussion before building"), workflow patterns, terminology — and writes them to disk. The next session can query what previous sessions learned. Six categories partition the knowledge: correction, preference, workflow, terminology, tool-routing, and methodology.
The session-learnings plugin hooks into OpenCode's message transform pipeline. When a user says "NO" or signals a correction, the plugin injects a nudge into the conversation prompting the model to call grounder_learnings(action: "record") immediately. Corrections are captured at the moment they happen, not retroactively. Duplicate detection prevents the same insight from being recorded twice.
"Don't do X, do Y." The sharpest category. When the model gets corrected, the learning captures both the wrong approach and the right one. Future sessions check corrections before repeating mistakes.
"I prefer..." statements. Design discussion before code. Terse commit messages. Specific formatting choices. These accumulate into a behavioral profile that shapes how the model works with a specific user.
Process-level insights that should eventually become flows, voices, or agent configurations. The staging area for patterns that haven't been formalized yet but keep recurring across sessions.
Reads session JSON from ~/.local/share/opencode/storage/. Three tiers: session metadata (time, slug, summary), messages (cost, tokens, model, agent), and parts (individual tool call records with name, status, duration). Read-only — grounder never mutates the source data.
Flowbot drives workflows, roost coordinates parallel sessions. Grounder provides the retrospective layer — after a flow completes or a session closes, grounder can analyze what happened, what it cost, and what failed.
The plugin bridges the gap between conversation and persistence. It watches message transforms for correction signals and triggers learning capture without the model needing to remember to do it. Ships as a plugin in grounder/plugins/.
The server that remembers what every other server forgets.