ContextVaultBack to overview
Technical FAQ

How ContextVault works

ContextVault is a local evidence engine for project context. It captures or imports source material, normalizes it into a shared model, and retrieves the relevant history without requiring a backend or AI API.

Browser export + Terminal sessions
                |
      ContextSession / ContextEvent
                |
        Local deterministic index
                |
 History / Retrieve / Prepare / Memory

Questions you can investigate today

What happened in the project during the last two weeks?

contextvault history --since 2w

What did Codex decide about authentication?

contextvault decisions auth --source codex

Show Redis problems and failed attempts captured this month.

contextvault problems redis --since 30d

Prepare the relevant auth context for the next agent.

contextvault prepare "auth middleware" --since 30d

These commands return dated source evidence. They do not fabricate a summary. Use contextvault prepare when you want to hand the retrieved evidence to a coding agent.

Architecture, privacy, and limits

Does ContextVault use an AI model to answer questions?

Not today. The engine retrieves source evidence deterministically from your local index. It does not send context to an API or generate a confident-sounding answer that is not grounded in your files. An optional local-model or provider adapter belongs in a later phase.

How do browser and terminal context become one history?

The extension keeps capturing to browser IndexedDB exactly as before. You export Markdown or ZIP, then contextvault import stores the original Markdown under .contextvault/imports/browser/. Terminal sessions already live under .contextvault/sessions/. Both are normalized into ContextSession and ContextEvent records when the local index is built.

What happens if I import the same conversation twice?

Browser session identity is derived from conversation_id. Identical content is skipped. A changed export for the same conversation updates the imported source file. ContextVault does not delete your external export.

Where is my data stored?

Browser capture stays in local IndexedDB. Project memory, imported browser exports, terminal sessions, links, indexes, and prepared packages stay inside the local .contextvault directory. There is no ContextVault backend, account, telemetry pipeline, or required sync service.

Is importing an untrusted ZIP safe?

ZIP entries are read as Markdown and are never extracted to their embedded filesystem paths. Generated filenames are sanitized. Imports are limited to 100 MB per archive, 10 MB per Markdown file, and 1,000 Markdown files. You should still treat the captured text itself as untrusted context.

How does retrieval rank results?

The current engine uses exact phrase matches, token matches, event-type importance, and recency. Filters can narrow by event type, source or browser platform, and time. Retrieval is lexical and deterministic; embeddings and semantic search are not silently running in the background.

Is there a Desktop app?

Yes. ContextVault Desktop provides a visual recorder plus session browsing, project search, prepared AI context packages, and exports — all without requiring the terminal. Windows and Linux installers are published on GitHub Releases; macOS is currently available as a local source build. It uses the same local .contextvault directory as the CLI, so both tools remain compatible.

How do I start recording in the Desktop app?

Add or select a project, then click Start recording. Desktop launches the bundled contextvault record process with that project as its working directory. Entries are sent to the real CLI, and Finish & save ends the process so its Markdown appears under .contextvault/sessions and in the Sessions screen.

Is Desktop a separate implementation from the npm package?

No. Desktop launches the bundled vault-terminal.mjs for recording and uses the same Context Engine and .contextvault files as the package. Major capabilities have dedicated GUI screens and forms; the raw command runner is an optional collapsed Advanced CLI Mode. There is no migration or parallel database.

Does automatic Desktop classification send my text to an AI service?

No. Classification uses deterministic on-device rules and makes no model, network, telemetry, or analytics request. The detected type is shown before you add the entry, and you can override it when needed.

Can Desktop manage more than one project?

Yes. Use + Add beside the project selector to register multiple local project folders, then switch between them from the sidebar. Each project keeps an independent .contextvault directory. Removing a project from the recent list never deletes its folder or vault data.

Does it automatically record every terminal or coding agent?

No. The bundled contextvault record command reads explicit entries from the terminal or Desktop GUI. Desktop watches the active .contextvault directory, so sessions written through the CLI or compatible agent integrations appear immediately. Silent interception of an unrelated Codex, Claude Code, Cursor, VS Code, or MCP process still requires an adapter and is not claimed.

Do I need to know CLI commands to use Desktop?

No. Recording, Sessions, History, Decisions, Problems, Tasks, Retrieve, Search, Prepare, Import, Link, Index, Memory, Timeline, and Export have GUI entry points. Common filters use fields and dropdowns, and results can be copied or exported. Raw arguments are available only in Advanced CLI Mode.

How do I know Desktop is synchronized with my project?

Dashboard and Sessions show Watching project, the last update time, event count, and detected sources. When ContextVault Markdown changes, the app rebuilds the local index and refreshes open views.

What is the source of truth?

Markdown is the durable source of truth. The JSON index, project timeline, generated memory block, and prepared context packages can be rebuilt from local Markdown sessions and imports.