From Conversation Recorder to Context Engine: Building Local-First Memory for AI Development

How ContextVault 1.3 unifies browser conversations, terminal sessions, and coding-agent decisions in one searchable local context engine — without a backend, tracking, or hidden AI calls.

You spend forty-five minutes walking a coding agent through a Redis connection bug. Together, you find the root cause, test a fix, and uncover a configuration detail that is not documented anywhere. Then the context window fills up. Two weeks later, the same bug appears in staging. The original session is gone, the browser conversation is buried, and the next agent knows nothing about what you already discovered. You start again. This is context fragmentation: project knowledge scattered across ChatGPT conversations, coding-agent sessions, terminals, accounts, models, and limited context windows. It creates a quiet tax on every AI-assisted workflow.

Exporting conversations helps, but only partially. A directory full of Markdown exports is still a directory full of disconnected files. The information is preserved, but it is not organized as project memory. That distinction changed the direction of ContextVault. What began as a browser conversation recorder evolved into a local-first context engine designed around a broader idea:

Git tracks code. ContextVault tracks context.

Why Exporting Conversations Is Not Enough

I originally built ContextVault as a Chrome extension for capturing conversations across multiple LLM platforms. The extension solved an immediate problem: preserving complete conversations locally and exporting them in portable formats.

But capturing browser conversations addressed only one surface.

The decisions that shaped a project were also happening inside Codex sessions, Claude Code investigations, Cursor workflows, terminal debugging, human notes, failed experiments, and task discussions. Those sessions often disappeared when a terminal closed or an agent reached its context limit.

I did not need another folder of exports. I needed a way to preserve what happened, classify it, search it, and prepare it for the next agent.

That led to three connected layers:

• Browser Capture
• Vault Terminal
• The Unified Context Engine

Layer One: Building Browser Capture

Browser Capture is the original ContextVault surface. It is a Chrome Manifest V3 extension that captures conversations from ChatGPT, Claude, Gemini, Perplexity, Poe, DeepSeek, and Copilot.

The extension uses a hybrid DOM and network capture strategy. It watches provider DOM mutations, observes supported network responses, assembles streamed messages in the content-capture layer, and sends finalized messages to the background service worker for local storage.

This hybrid approach matters because LLM interfaces are dynamic. Assistant responses arrive incrementally, DOM elements change while streaming, and provider implementations differ.

Once captured, conversations remain in IndexedDB by default. Users can export them as individual Markdown files or bulk ZIP archives. Each exported conversation includes YAML frontmatter containing metadata such as platform, model, date, conversation ID, and tags.

The data flow is intentionally contained:

Provider page
    ↓
DOM and supported network capture
    ↓
Stream assembly
    ↓
Background service worker
    ↓
Local IndexedDB storage
    ↓
Explicit Markdown or ZIP export

The extension does not send captured conversations to a ContextVault server because no ContextVault server exists. It does not require an account, collect telemetry, or call an external AI API.

Browser Capture solved the first problem: preserving conversations. It did not yet solve project memory.

Layer Two: Building Vault Terminal

Browser conversations are only part of an AI development workflow. Important context also appears while working with coding agents and terminals: a failed authentication fix, a decision about middleware boundaries, an unresolved production problem, a task discovered during debugging, a note explaining why one approach was rejected.

Vault Terminal provides an explicit way to record those moments. It is a Node.js CLI published on npm as @aliabdm/contextvault.

Run it directly without installing anything globally:

npx @aliabdm/contextvault init

Or install globally:

npm install -g @aliabdm/contextvault
contextvault init

To start recording:

contextvault record

Inside the recorder, context is entered using typed commands:

/source codex
/title Fix auth middleware

/user The login redirect is broken.

/agent I found the issue in middleware order.

/decision Keep auth checks in middleware and policy checks in controllers.

/task Add a regression test for the redirect loop.

/problem The session cookie is missing on callback.

/end

These commands become structured context events. Each session is saved as a local Markdown file under .contextvault/sessions/. The files are human-readable, inspectable, searchable with standard tools, easy to archive, and ignored by Git by default.

There is no automatic summarization, rewriting, or external model call. Vault Terminal records what you explicitly provide. It does not intercept every terminal process or automatically capture complete Codex, Claude Code, or Cursor sessions. That limitation is deliberate and visible.

The CLI also supports:

contextvault list
contextvault search "Redis"
contextvault export

Vault Terminal solved the second problem: preserving agent work, decisions, tasks, problems, and notes outside the browser.

The next challenge was connecting both capture surfaces.

Layer Three: Building the Unified Context Engine

The Unified Context Engine turns separate captures into searchable project context. It imports Browser Capture exports, reads Vault Terminal sessions, normalizes both sources into shared models, and builds a local index.

Browser exports can be imported from Markdown files, ZIP archives, or directories:

contextvault import ./chatgpt-export.md
contextvault import ./contextvault-export.zip
contextvault import ./browser-exports/

The importer reads Markdown entries in memory, validates ContextVault frontmatter, sanitizes filenames, prevents unsafe archive extraction, applies deterministic duplicate detection, and enforces safety limits.

Current limits:

• 100 MB per archive
• 10 MB per Markdown file
• 1,000 files per import ZIP entries are processed in memory rather than extracted to arbitrary disk paths. If the same export is imported twice, the duplicate is skipped. If an updated export shares the same conversation_id, the existing source is updated rather than duplicated.

Normalizing Different Context Sources

Browser chats and terminal sessions do not begin with the same structure. The normalization layer maps both into two shared models: ContextSession and ContextEvent.

Browser messages are mapped as user and agent events, with platform and role metadata preserved. Terminal events retain their explicit types: user, agent, decision, task, problem, and note.

The normalizer also supports legacy snake_case metadata fields — started_at, ended_at, git_branch — alongside current camelCase fields. This keeps existing Markdown sessions readable without requiring a destructive migration.

Building the Local Index

After importing or recording context, rebuild the index with:

contextvault index

The engine reads terminal sessions and imported browser conversations, normalizes them, and writes a local JSON index to .contextvault/index/context-index.json.

Markdown remains the source of truth. The JSON index is derived data. If it becomes corrupted or outdated, delete it and rebuild from the original Markdown files:

Local Markdown
    ↓
Normalize
    ↓
Rebuildable JSON index

There is no proprietary database format and no dependency on a hosted service. Users can inspect, edit, archive, or process their context without ContextVault.

Retrieving Evidence Across Capture Surfaces

Once indexed, context can be queried across both surfaces:

contextvault history --since 2w
contextvault decisions auth --source codex
contextvault problems redis --since 30d
contextvault retrieve "auth middleware" --type decision,task

Supported filters: --type, --source, --since, --limit.

Retrieval is local and deterministic. Ranking considers phrase matches, token matches, event-type boosts, and recency. It does not use embeddings, vector databases, semantic search, external models, or hidden AI calls.

The engine answers: What have I captured about this topic?

It does not claim to answer: What does all my project data mean?

The first question is grounded and testable. The second requires a semantic retrieval layer that ContextVault does not currently include.

Preparing Context for the Next Agent

The prepare command creates a focused context package:

contextvault prepare "auth middleware"

The generated file is written to .contextvault/exports/prepared-context.md. It can include project memory, relevant sessions, decisions, tasks, problems, and source metadata — portable Markdown that can be handed directly to Codex, Claude Code, Cursor, or another AI tool.

ContextVault does not call those tools. It prepares grounded context for the user to move explicitly.

Architecture Overview

The architecture separates four responsibilities:

• Capture preserves browser or terminal context
• Normalization converts sources into shared records
• Indexing and retrieval make those records searchable
• Preparation produces portable context for another agent This separation creates boundaries for future adapters without changing the core storage model.

Integrations are adapters. The engine is the product.

Why Markdown Remains the Source of Truth

Project context should remain usable without the application that created it. A proprietary database can be fast, but it also creates dependency and obscures the raw material.

Markdown provides different guarantees: it opens in any editor, works with standard search tools, can be archived directly, remains readable if ContextVault disappears, and can be transformed with scripts or moved between tools.

The JSON index exists for retrieval performance. It is disposable. The Markdown is not.

Git tracks code history. ContextVault preserves the discussions, failed attempts, decisions, and discoveries surrounding that code.

Privacy by Design

ContextVault follows a local-first model. No captured data is sent to a ContextVault backend because there is no backend.

• No backend — data remains on the local machine
• No accounts — users control their own context
• No telemetry — no usage tracking of any kind
• No external AI calls — terminal capture and retrieval work entirely locally
• No automatic cloud sync — files stay where you put them
• No hidden model calls — retrieval stays deterministic The .contextvault/ directory is ignored by Git by default. This matters because raw sessions may contain prompts, local paths, environment details, logs, debugging output, and potential secrets. Automatically committing that material would be an irresponsible default.

Users can choose how to archive or back up their files. ContextVault does not make that choice for them.

What ContextVault Does Not Do Yet

A useful technical project should make its boundaries as visible as its features.

No automatic terminal-agent interception. Vault Terminal captures what the user explicitly records. It does not hook into every shell process or capture complete Codex, Claude Code, or Cursor sessions.

No semantic search. Retrieval is lexical and deterministic. Optional local semantic indexing is future work.

No built-in natural-language answers. ContextVault retrieves evidence and prepares context packages. It does not synthesize answers. Users provide the prepared Markdown to the model they choose.

No automatic IndexedDB synchronization. Browser conversations enter the Context Engine through explicit Markdown or ZIP export and import. The extension does not automatically synchronize with .contextvault/.

Browser adapters can change. LLM providers regularly modify their interfaces. Provider changes may require adapter updates, and the generic adapter remains best-effort.

These are not hidden limitations. They are the honest boundaries of ContextVault 1.3.

Who ContextVault Is For

ContextVault is useful when:

• You switch between ChatGPT, Codex, Claude Code, Cursor, or other tools
• Coding-agent context windows reset during ongoing work
• You need to revisit what an agent attempted several days ago
• You want a searchable record of project decisions and problems
• You need portable context packages that can move explicitly between tools
• You want local ownership without accounts or telemetry It is especially relevant for developers whose AI workflow has grown larger than any single conversation.

Why Not Just Use a Notes App?

Notes applications are useful for polished summaries. They are less effective at preserving raw working context: the failed attempt before the fix, the partial command output that revealed the bug, the agent response that influenced a decision, the unresolved problem discovered during another task, the reason an architectural approach was rejected.

ContextVault preserves that intermediate state. An /agent event records what the agent said — not what you later remember. A /decision event captures an explicit project decision. A /problem event keeps an unresolved issue available for future retrieval.

ContextVault is not a replacement for documentation. It is the context layer that makes future documentation easier to produce because the underlying evidence remains searchable.

Roadmap

The Unified Context Engine now exists. The next phase is reducing manual handoffs and improving retrieval without weakening the local-first model.

MCP Server — Expose project context through the Model Context Protocol so compatible agents can query it through an explicit integration.

VS Code Extension — Surface project decisions, tasks, problems, and related sessions directly inside the editor.

Agent Integrations — Build adapters for Codex, Claude Code, Cursor, and similar tools that can emit the shared context structure automatically.

Optional Local Semantic Indexing — Improve ranking with optional local embeddings while preserving the existing deterministic retrieval path.

Encrypted Backups and Optional Self-Hosted Sync — Support off-machine durability without requiring a third-party hosted service.

These are roadmap items, not implemented features. The current architecture provides the shared models, normalization layer, index schema, and adapter boundaries needed to build them incrementally.

Try ContextVault

ContextVault is fully open source and available today under the MIT License.

Initialize Vault Terminal directly from npm:

npx @aliabdm/contextvault init

Or install it globally:

npm install -g @aliabdm/contextvault
contextvault init

Start recording:

contextvault record

Build and query the local context index:

contextvault index
contextvault history --since 2w
contextvault retrieve "auth middleware"

Capture browser conversations, record coding-agent sessions, build a local context index, and prepare grounded context packages — all while keeping your data on your own machine.

Project links:

• GitHub
• npm Package
• Live Demo
• Technical FAQ If you try ContextVault, I'd genuinely appreciate technical feedback. Does retrieval surface the context you expected? Is there a command or workflow you think is missing? How would you improve the developer experience?

Feel free to open an issue, submit a pull request, or connect with me on LinkedIn.

About the Author

Mohammad Ali Abdul Wahed is a Senior Software Engineer specializing in backend systems, Laravel, distributed applications, and AI developer tooling. He is the creator of ContextVault, an open-source local-first context platform that combines a Chrome Extension and an npm CLI to preserve browser conversations, coding-agent sessions, project decisions, and developer workflows across AI tools.

GitHub · LinkedIn · Portfolio