Knowledge & Sessions
MultiTerminal remembers two kinds of things: knowledge — the durable decisions, patterns, and gotchas worth keeping — and sessions — the full transcripts of past work you can search back through. Both live in SQLite and are reachable from MCP tools, so an agent can store what it learns and recall what was done before.
On This Page
The Knowledge Base
The knowledge base is institutional memory: short, titled entries capturing things the team has learned. It is stored in the knowledge_entries table and managed by KnowledgeDatabase, which shares the same SQLite file (and FTS5 full-text index) as the task board. Each entry has a category describing what kind of knowledge it is:
| Category | Use it for |
|---|---|
decision | A choice that was made and why. |
pattern | A reusable approach that works here. |
gotcha | A surprising trap or footgun to avoid. |
anti_pattern | An approach that looks reasonable but should not be used. |
debug_insight | A root cause or diagnosis worth remembering. |
preference | A team or owner preference about how things are done. |
An entry also carries an optional project ID (null means the entry is global), comma-separated tags, the source it came from (manual, session, task, and similar), and a confidence level. Confidence has three values, set when adding: confirmed (the default), likely, and uncertain. Separately, an entry has a lifecycle state: it can later be deprecated, which retires it and excludes it from search results by default. Deprecation is a state change, not a confidence level — and it can point at the newer entry that supersedes it (via superseded_by), so you can follow the chain.
Storing Knowledge
Add an entry with the add_knowledge MCP tool. It requires a title, the content, and a category; everything else (project, tags, source, confidence) is optional. A good entry is a single, self-contained lesson with a title you would actually search for later — for example a gotcha titled “WebView2 host objects must be added before navigation” rather than a vague note.
Capture knowledge at the moment you learn it — right after a tricky debug, a design decision, or discovering a constraint — while the detail is fresh. That is what makes it useful to the next agent who hits the same wall.
Recalling Knowledge & Attention Decay
Search the base with query_knowledge, passing a free-text query and optionally a category, project, or tag filter. Search uses FTS5 full-text matching when available and falls back to a LIKE query otherwise; deprecated entries are left out unless you ask for them.
Every time an entry is queried or injected into context, its reference count is bumped and its “last referenced” timestamp is updated. That feeds an attention-decay ranking used when surfacing the most relevant memory:
score = (reference_count + 1) / (days_since_last_referenced + 1)Entries that are referenced often and recently rank highest; an entry that has not been touched in a long time decays toward the bottom even if it was once popular. The effect is that memory which is still being used stays prominent, while stale memory quietly recedes without having to be deleted.
Session Memory & History
Beyond curated knowledge, MultiTerminal keeps the raw record of past work. Claude Code writes each session to a JSONL transcript on disk; SessionLineageService imports those transcripts into SQLite — a session_lineage record per session plus the extracted messages in session_messages, indexed for full-text search. A separate session-memory store additionally chunks transcripts and embeds them for semantic search.
Importing happens a few ways: import_session brings in a single transcript and links it to a task; sync_sessions incrementally scans a Claude project folder and imports any sessions not already stored, skipping ones it has seen for a fast re-sync.
Finding Past Work
There are two complementary ways to search the history, plus a shortcut for the most common need:
| Tool | What it does |
|---|---|
search_session_history | Full-text (FTS5, with LIKE fallback) search across imported session messages. Filter by task, role (user/assistant), agent, or free text. Best when you remember roughly what was said. |
search_session_memory | Semantic search over transcript chunks using vector embeddings plus FTS5. Finds context by meaning, not just keywords — ask it a natural-language question like “what was the WebView2 event bridge approach?” |
get_latest_session | Returns the most recent previous session for a project (with its cached summary, or recent messages if none), filterable by agent. Use it at session start to recall what was last worked on. |
Reach for search_session_history when you remember the words; reach for search_session_memory when you only remember the idea.
Lineage Chains
Sessions are not isolated — they form lineage chains. When one session continues from another (an agent cycling through coding then review, or a session rolling over), the new session records the previous one as its parent. get_session_lineage walks that parent chain to reconstruct the full history of a task from root to leaf, and get_task_sessions lists every session linked to a task with its agent, type, and parent links. Together they let you replay how a piece of work actually unfolded across multiple sessions and agents.
For the institutional-memory tools alongside the rest of the MCP surface, see the MCP Tools reference; for how all of this is wired together, see the Architecture overview.