Session Knowledge Base

This page covers the "Session Knowledge Base", "Processing history" and "Archived Sessions". Managing, editing and importing local Markdown files is covered in Local Knowledge Bases.

The Session Knowledge Base stores knowledge, decisions, constraints and lessons learned, organized as project → session → entry. Generated entries are stored on their own: they do not change when their source session changes, and you can edit them by hand. The Session Knowledge Base belongs to the VelaTerm backend you are connected to and is shared across its projects and sessions; when you connect to another server, you see that server's knowledge base.

It is separate from session content search. Session search finds text in the original conversations, while the knowledge base searches only saved entries. VelaTerm organizes, stores and displays entries when you ask it to; it does not add entries to new sessions automatically.

Organizing a session

Right-click a session in the sidebar or its tab and choose "Organize into Session Knowledge Base". The same action is available for archived sessions.
Choose the "Agent": Claude, Codex, Grok Build, OpenCode, Pi or OMP. VelaTerm uses the executable path set in Settings ▸ Agents, or finds the program on PATH. An agent that cannot be found is listed as "Not installed or configured" and cannot be selected.
Optionally choose a "Model (optional)" and a "Thinking effort". "Default model" and "Agent default" leave the choice to the agent's own configuration. The model list is the same one used when you create a session, and effort levels appear only for models that offer them. VelaTerm remembers the last agent, model and effort you used. The agent must be signed in and have access to the chosen model.
Click "Organize and save". The selected agent receives the session's text and processes it through its own model configuration.
Follow the task under "Processing history". Closing the dialog does not stop the task.

VelaTerm reads the agent's conversation record when one is available. Otherwise it uses the session's terminal recording (see Terminal Usage) with terminal control codes removed. When neither can be read, it reports "No readable conversation is available for this session." A terminal recording contains the visible screen text and may include redrawn content, so the organizing agent should not treat such output as verified fact.

A source snapshot stores the text that was read for organizing. Project and session names are saved when a session is first added and are not updated when the project or session is later renamed, moved, archived or deleted elsewhere.

Organizing a session again reads it again and replaces the entries previously generated from it, including your manual edits; this happens even when the text and the model settings are unchanged. If the session already has an unfinished task, the new task replaces it. When the old task is already running, the new one starts automatically after the old process has stopped ("This task will start automatically once the previous task for this session has stopped."); the old task remains in the history.

How organizing works

Organizing has three stages, shown as the task's progress:

Extracting topics: the session is read in sections, and reusable knowledge is extracted. Topics are merged only within this task; other sessions' entries and earlier manual edits are not used.
Merging knowledge: the contributions for each topic are combined, keeping knowledge, constraints and uncertainty. The agent is instructed to account for later corrections and contradictions and not to invent conclusions.
Saving entries: VelaTerm checks the fields, sources, links and versions and replaces the session's generated entries in a single database transaction. An entry with the same title keeps its identity and gets a new revision. Entries that are no longer generated are deleted together with their revision history, and links pointing to them are removed. When organizing succeeds but finds nothing reusable, the session's old generated entries are cleared ("No reusable knowledge was extracted. Previously generated entries for this session have been cleared."). A failed check, a cancellation or a version conflict keeps the previous entries unchanged, and no partial result is saved.

The agent returns structured content, and VelaTerm performs all database changes. Entries link to each other, and "Linked from" lists are computed automatically. Source snapshots and revision history remain available even if the original session is deleted.

The quality of organized knowledge still needs your judgment. If something is wrong, edit the entry or restore an earlier revision; restoring creates a new revision and keeps the version you replaced.

Processing history

"Processing history" lists organizing tasks, 40 per page. Each task shows the agent, the model ("Default model" when none was chosen), the thinking effort and the time; a running task also shows its current stage ("Extracting topics", "Merging knowledge" or "Saving entries"). A task's status is "Waiting to start", "In progress", "Cancelling", "Completed", "Failed" or "Cancelled", and its "Source snapshot" and resulting entries can be opened from the list.

"Cancel" stops a task that is waiting or running. A running task shows "Cancelling" until the agent process has stopped. Canceling does not delete the source snapshot.
"Retry" restarts a failed or canceled task with the same source snapshot, model and thinking effort. The history shows the settings the task was created with; a default choice means the agent decided, not that VelaTerm resolved a specific model.

Different sessions can be organized in parallel. Each session runs one task at a time, and submitting it again keeps only the newest waiting task instead of building a queue. Waiting tasks are saved in the database and continue after the app restarts. A running task that has not reported progress for two minutes is marked as interrupted ("Processing was interrupted. Retry to process the saved source snapshot."). Time spent waiting does not count toward the task's time limit.

You can edit entries while organizing runs. If someone edits or deletes the session's generated entries during a task, the task reports a version conflict, your changes are kept, and you can retry afterwards. Different sessions may use the same entry title; titles must be unique within one session.

Browsing and maintaining entries

Open the knowledge base from the right panel (see Local Knowledge Bases) and expand "Session Knowledge Base" by project, session and entry. Click a project or session to list its entries, and click an entry to read it. The "Up one level" button returns to the parent page.

The list page offers search ("Search entry titles and content…"), a tag filter ("All tags"), sorting by "Recently updated" or "Title", and refresh. Search covers titles, summaries, bodies and tags, supports multiple words (all must match) and ranks title matches first; each result also lists its directly related entries. When there are no exact matches, approximate matches are shown, as in local knowledge base search.
A session's entries are shown 40 per page; project and session lists are not cut off by this limit, and long tree lists offer "Load more".
An entry page shows the Markdown body, "Related entries", "Linked from", "Sources" and "Revision history". You can edit the body in place and save with ⌘S / Ctrl+S, "Edit" the title, summary and tags, "Export Markdown", "Copy to a local notebook" or "Delete". Deleting an entry also deletes its revision history but keeps the source session and its snapshots.
"New entry" creates an entry by hand; such entries appear in the "Manually created" group.

The tree also supports management actions:

Right-click an entry to rename or delete it; drag it onto another session to reassign it.
Right-click a project or session group to rename it or delete its entries. Renaming a group also renames the real project or session. Deleting a group removes only its knowledge entries: "Delete all N knowledge entries in this group? The project or session itself is kept."
Dragging a session onto another project moves the real session to that project.
The "Manually created", "Previously merged entries" and "Unknown source project" groups cannot be renamed.

Entry pages, edit forms, source snapshots, revisions, the organize dialog and the processing history all have their own URLs, and the selected project, session, search, filter, sorting and page are part of the URL.

Archived Sessions

Archived sessions are managed in the knowledge base. "Archived Sessions" appears in the knowledge base tree next to the "Session Knowledge Base" and groups archived sessions by the project they came from; the "Archived Sessions" button in the sidebar header opens the same place.

The main area lists all archived sessions by project. An opened session has two tabs: "Conversation" shows the full conversation, and "Knowledge entries" shows the entries generated from it.
"Search archived content…" searches the full text of archived sessions only and groups the matches by session.
An opened archived session offers "Restore to normal session", "Organize into Session Knowledge Base", "Export full context as Markdown" (for Claude and Codex sessions) and "Delete permanently (with recording)". Deleting permanently takes effect immediately, without a confirmation step.
Archiving, restoring and deleting a session do not change existing knowledge entries, because entries and source snapshots are stored separately. A restored session can continue its conversation.

Data from earlier versions

When VelaTerm upgraded older data, entries with a single source session were assigned to that session. Entries that had already combined several sessions were kept intact in the "Previously merged entries" group; they are not split and are never replaced by organizing one of those sessions again. Entries without a source went to "Manually created". Project information that still existed was filled in once during the upgrade; sources whose project could not be determined are listed under "Unknown source project" with their original session names and snapshots.

Data and limits

The Session Knowledge Base is stored in the application's SQLite database (memory_* tables), separate from the session search index. The interface holds only what it displays and unsaved form input; validation, version checks, duplicate detection and all writes happen in the backend.

A source can contain up to 2,000,000 characters, each extraction section up to 24,000 characters, one model input up to 350,000 characters, and one entry body up to 200,000 characters.
Each agent call may run for up to 10 minutes, and each of its output streams may produce up to 8 MiB.
For OpenCode, Pi and OMP, the text passed in one call is limited to 128 KiB.
If an agent returns output that does not match the expected structure, VelaTerm asks it again, up to three times.

Anything over these limits fails clearly ("The source, context or output exceeds the supported size. Nothing was truncated or saved."); nothing is truncated and saved.

Organizing is recorded in logs/runtime-*.log in the application data directory. When VLX_LOG_DIR is not set, VLX_MEMORY_LOG_DIR sets the directory. VLX_MEMORY_LOG_LEVEL=error records only errors, and off turns this module's log off. The log records tasks and stages, input and output counts, durations, character counts, SHA-256 digests and token usage figures. It never records full prompts, source text, model responses, credentials or error output; the source snapshots hold the original material.

Code graph links

Knowledge entries can be linked to code symbols, and "Code references" on an entry page jumps to the code graph. When the linked file changes, the entry shows that it needs review; confirming the review does not change the entry's text. Agents in a session can query code and entries with vkb. See Code Graph & Knowledge Base.