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.

Does it automatically record every terminal or coding agent?

No. Vault Terminal records the context you explicitly enter. Automatic Codex, Claude Code, Cursor, VS Code, and MCP adapters are future integrations. This boundary avoids hidden interception and keeps the current behavior predictable.

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.