{"_id":"@aliabdm/contextvault","name":"@aliabdm/contextvault","dist-tags":{"latest":"1.3.0"},"versions":{"1.3.0":{"name":"@aliabdm/contextvault","version":"1.3.0","description":"A local-first context platform for AI chats, coding agents, and project memory.","type":"module","engines":{"node":">=20"},"bin":{"contextvault":"scripts/vault-terminal.mjs"},"scripts":{"dev":"vite","build":"tsc && vite build","preview":"vite preview","vault:init":"node scripts/vault-terminal.mjs init","vault:record":"node scripts/vault-terminal.mjs record","vault:list":"node scripts/vault-terminal.mjs list","vault:show":"node scripts/vault-terminal.mjs show","vault:export":"node scripts/vault-terminal.mjs export","vault:search":"node scripts/vault-terminal.mjs search","vault:index":"node scripts/vault-terminal.mjs index","vault:import":"node scripts/vault-terminal.mjs import","vault:retrieve":"node scripts/vault-terminal.mjs retrieve","vault:prepare":"node scripts/vault-terminal.mjs prepare","vault:memory":"node scripts/vault-terminal.mjs memory","vault:link":"node scripts/vault-terminal.mjs link","vault:timeline":"node scripts/vault-terminal.mjs timeline","vault:history":"node scripts/vault-terminal.mjs history","vault:tasks":"node scripts/vault-terminal.mjs tasks","vault:decisions":"node scripts/vault-terminal.mjs decisions","vault:problems":"node scripts/vault-terminal.mjs problems","demo:vault-terminal":"python scripts/generate-vault-terminal-demo-gif.py","test":"vitest run","test:watch":"vitest","docker:build":"docker build -t llm-history-observer .","docker:dev":"docker compose up --build","docker:down":"docker compose down"},"devDependencies":{"@crxjs/vite-plugin":"^2.7.0","@types/chrome":"^0.0.270","typescript":"^5.5.4","vite":"^7.3.6","vitest":"^4.1.9"},"dependencies":{"js-yaml":"^5.2.0","jszip":"^3.10.1"},"_id":"@aliabdm/contextvault@1.3.0","_integrity":"sha512-bCzj8omb5xYR2ewOQQ+shJScBL5jGrIdbgdCF8bmlw2P8rTgcHG2KWF+XPWWLlo8lzh+TntuWumuYljHXsYTUg==","_resolved":"/release/contextvault-1.3.0.tgz","_from":"file:/release/contextvault-1.3.0.tgz","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-bCzj8omb5xYR2ewOQQ+shJScBL5jGrIdbgdCF8bmlw2P8rTgcHG2KWF+XPWWLlo8lzh+TntuWumuYljHXsYTUg==","shasum":"e3caedbca2870283bd9ffcbcd5a2bead8894339a","tarball":"https://registry.npmjs.org/@aliabdm/contextvault/-/contextvault-1.3.0.tgz","fileCount":5,"unpackedSize":68187,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGpwhBJN4e4Et6rQBquQMHolDTAaLiGckzBMSRsARf9MAiEA9UgaSfC8fPQh0N9TNewMFmjtpkSKydZCNG6YjlCuppU="}]},"_npmUser":{"name":"aliabdm","email":"aliabdm@gmail.com"},"directories":{},"maintainers":[{"name":"aliabdm","email":"aliabdm@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/contextvault_1.3.0_1782584746747_0.4229074631853258"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-27T18:25:46.566Z","1.3.0":"2026-06-27T18:25:46.903Z","modified":"2026-06-27T18:25:47.136Z"},"maintainers":[{"name":"aliabdm","email":"aliabdm@gmail.com"}],"description":"A local-first context platform for AI chats, coding agents, and project memory.","readme":"

\n \"ContextVault\n

\n\n

ContextVault

\n

Your local-first memory layer for AI chats, coding agents, and project context.

\n\n

\n ContextVault captures context from browsers and terminals, stores it locally, and exports it as portable Markdown.\n It helps preserve LLM conversations, coding-agent sessions, project decisions, tasks, problems, and workflow context\n across tools.\n

\n\n

\n Landing Page\n ·\n Install\n ·\n Vault Terminal\n ·\n Technical FAQ\n ·\n Roadmap\n

\n\n

\n \"version\"\n \"license\"\n \"build\"\n \"privacy\"\n \"capture\n

\n\n

\n No backend.\n No accounts.\n No tracking.\n

\n\n---\n\n## Demo\n\n\n \n \n \n \n
\n

Browser Capture

\n

\n \"ContextVault\n

\n 		\n

Terminal Capture

\n

\n \"ContextVault\n

\n
\n\n### Unified Context Engine\n\n

\n \"ContextVault\n

\n\n

\n Watch the MP4 demo\n

\n\n\n \n \n \n \n \n
Browser Capture
ChatGPT, Claude, Gemini, Perplexity, Poe, DeepSeek, Copilot		Terminal Capture
Codex, Claude Code, Cursor workflows, human notes, decisions, tasks		Local Memory
IndexedDB, local Markdown, exportable archives, no backend
\n\n## What It Does\n\nContextVault is a local-first context platform with two first-class capture surfaces:\n\n- **Browser Capture** records conversations from supported LLM web apps.\n- **Terminal Capture** records human, AI, and coding-agent work sessions from the terminal.\n\nBoth surfaces store context locally. Browser exports can now be imported into the same Context Engine used by terminal sessions, so retrieval and prepared context packages can combine conversations and agent work without changing extension behavior.\n\n---\n\n## Two Capture Surfaces\n\n

\n \"browser\n \"terminal\n \"local\n \"markdown\n

\n\n### Browser Capture\n\nCaptures conversations from:\n\n- ChatGPT\n- Claude\n- Gemini\n- Perplexity\n- Poe\n- DeepSeek\n- Copilot\n\nBrowser Capture uses a hybrid DOM + network capture engine and exports conversations as structured Markdown or ZIP files.\n\n### Terminal Capture\n\nCaptures:\n\n- Codex sessions\n- Claude Code sessions\n- Cursor workflows\n- Human notes\n- Decisions\n- Tasks\n- Problems\n- Project context\n\nTerminal Capture stores everything as local Markdown memory under `.contextvault/`.\n\n---\n\n## Why It Exists\n\nAI work is powerful, but context is fragmented across too many places:\n\n| Problem | Consequence |\n| --- | --- |\n| Switch models | Lose thread continuity |\n| Hit token limits | Forced truncation |\n| Change accounts | Orphaned conversations |\n| Switch platforms | Context gets trapped in one tool |\n| Switch coding agents | Decisions and attempts disappear |\n| Work in terminals | Agent sessions are hard to preserve |\n| Revisit old ideas later | No portable memory or search surface |\n\nContextVault fixes this by making browser conversations and terminal work sessions **portable, local, and reusable**.\n\n---\n\n## Vision\n\nGit tracks code.\n\nContextVault tracks context.\n\nThe goal is to preserve knowledge, decisions, discussions, tasks, discoveries, and agent work across tools.\n\nContext should survive:\n\n- model switching\n- platform switching\n- account switching\n- agent switching\n- context window limits\n\n---\n\n## Features\n\n

\n \"Chrome\n \"Vault\n \"shared\n \"local\n

\n\n| Feature | Description |\n| --- | --- |\n| Browser Capture | Captures LLM conversations from supported browser platforms |\n| Terminal Capture | Captures coding-agent, human, and project-context sessions from the terminal |\n| Hybrid browser engine | DOM + network capture for browser reliability |\n| Local-first storage | Browser chats stay in IndexedDB; terminal sessions stay in `.contextvault/` |\n| Markdown export | Browser and terminal context can be exported as Markdown |\n| ZIP export | Browser conversations can be exported in bulk as ZIP |\n| Tags and project grouping | Organize captured browser conversations |\n| Raw terminal memory | Preserve `/user`, `/agent`, `/decision`, `/task`, `/problem`, and `/paste` blocks without rewriting |\n| Shared context model | Provider-agnostic context types for future browser, terminal, editor, and agent integrations |\n| Unified browser import | Import ContextVault Markdown, ZIP, or export directories into the shared local engine |\n| Cross-surface retrieval | Retrieve relevant browser messages and terminal events in one query |\n| Focused context views | List recorded tasks, decisions, and problems across the unified index |\n| Private by default | No backend, no accounts, no telemetry, no external AI API calls |\n\n---\n\n## Architecture\n\n

\n \"browser\n \"terminal\n \"shared\n \"Markdown\n

\n\n```text\nBrowser Capture Terminal Capture\nDOM Observer + Network Monitor Vault Terminal CLI\n | |\nStream Assembler Raw Context Events\n | |\nCapture Engine Markdown Sessions\n | |\nBackground Service Worker .contextvault/\n | |\nIndexedDB Storage Local Filesystem Storage\n | |\n Markdown / ZIP Export Sessions\n \\ /\n \\ /\n -------- Shared Context Layer ------\n |\n Context Engine\n Normalize / Index / Retrieve\n Prepare / Memory / Link\n |\n Markdown / ZIP / Timeline\n```\n\nBrowser key idea:\n\n- **DOM** = source of truth\n- **Network** = enhancement layer\n- **Stream Assembler** = final message builder\n\nTerminal key idea:\n\n- **Raw input** = source of truth\n- **Markdown files** = durable memory\n- **No summarization** = no context loss\n\n---\n\n## Privacy By Design\n\n

\n \"no\n \"no\n \"no\n \"private\n

\n\nContextVault is built around strict privacy principles:\n\n| No | Yes |\n| --- | --- |\n| No backend | Everything stays local |\n| No accounts | You control your own context |\n| No telemetry | Export when you choose |\n| No external AI APIs | Terminal capture works without calling AI services |\n| No automatic cloud sync | Local files and local browser storage by default |\n\nThe `.contextvault/` folder is ignored by git by default because terminal sessions may contain raw private context, paths, prompts, logs, secrets, or customer information.\n\n---\n\n## Installation (Dev Mode)\n\n```bash\nnpm install\nnpm run build\n```\n\nThen:\n\n1. Open `chrome://extensions`\n2. Enable **Developer Mode**\n3. Click **Load unpacked**\n4. Select the `dist/` folder\n\n### Or Use Docker\n\n```bash\ndocker compose up dev\n```\n\nThis runs the extension in dev mode on `http://localhost:5173` with hot-reload.\n\nAfter building, load `dist/` into Chrome as an unpacked extension.\n\nTo run the mock test server:\n\n```bash\ndocker compose --profile testing up dev test-server\n```\n\nThis starts both the dev server and an Nginx container serving the ChatGPT mock HTML at `http://localhost:8080`.\n\n---\n\n## How To Test Browser Capture\n\n1. Open **ChatGPT / Claude / Gemini**\n2. Start a conversation\n3. Open the extension popup\n4. Verify messages are captured\n5. Export as `.md` or `.zip`\n6. Confirm clean structured output\n\n---\n\n## Vault Terminal\n\nVault Terminal captures terminal-based human, AI, and coding-agent work sessions as raw Markdown context.\n\nIt is intentionally independent from the Chrome extension so browser adapters, popup behavior, permissions, IndexedDB storage, Markdown export, and ZIP export remain intact.\n\n### Terminal Commands\n\nThe package exposes a standard `contextvault` binary. The existing `npm run vault:*` scripts remain available for repository development.\n\nTo use the packaged CLI from a local clone:\n\n```bash\nnpm install\nnpm link\ncontextvault init\n```\n\nThe package is prepared for npm distribution, but registry publication is intentionally tracked as a separate release action.\n\nInitialize local terminal memory:\n\n```bash\nnpm run vault:init\n```\n\nStart an interactive recorder:\n\n```bash\nnpm run vault:record\n```\n\nInside the recorder:\n\n```text\n/source codex\n/title Fix auth middleware\n/user The login redirect is broken.\n/agent I found the issue in middleware order.\n/decision Keep auth checks in middleware and policy checks in controllers.\n/task Add regression test for redirect loop.\n/problem Session cookie is missing on callback.\n/paste\nRaw multiline content goes here.\n/endpaste\n/end\n```\n\nList saved sessions:\n\n```bash\nnpm run vault:list\n```\n\nShow the latest session or a specific session:\n\n```bash\nnpm run vault:show -- latest\nnpm run vault:show -- \n```\n\nExport project memory and recent sessions:\n\n```bash\nnpm run vault:export\n```\n\nSearch saved terminal sessions:\n\n```bash\nnpm run vault:search -- auth\nnpm run vault:search -- \"Claude Code\"\n```\n\nVault Terminal writes local files under `.contextvault/`:\n\n```text\n.contextvault/\n config.json\n memory.md\n imports/\n browser/\n sessions/\n exports/\n```\n\n### Technical Key Points\n\n- Vault Terminal is a plain Node.js CLI in `scripts/vault-terminal.mjs`.\n- It uses only local filesystem storage.\n- It writes Markdown sessions to `.contextvault/sessions/`.\n- It writes combined exports to `.contextvault/exports/contextvault-terminal-export.md`.\n- It preserves raw input exactly as typed for `/user`, `/agent`, `/note`, `/decision`, `/task`, `/problem`, and `/paste` blocks.\n- It adds a provider-agnostic context model under `src/shared/context/types.ts` for future browser, terminal, editor, or agent integrations.\n- It does not add backend, auth, telemetry, analytics, or external AI API calls.\n\n---\n\n## Unified Context Engine\n\nThe Context Engine turns imported browser conversations and recorded terminal sessions into searchable, reusable project memory while keeping Markdown as the source of truth.\n\n### Import Browser Conversations\n\nExport a conversation as Markdown or all conversations as ZIP from the extension, then import it into the project vault:\n\n```bash\nnpm run vault:import -- ./chatgpt-export.md\nnpm run vault:import -- ./contextvault-export.zip\nnpm run vault:import -- ./browser-exports/\n```\n\nDirect package command:\n\n```bash\ncontextvault import ./contextvault-export.zip\n```\n\nImported source files are stored under `.contextvault/imports/browser/`. Re-importing identical content is skipped. A changed export with the same `conversation_id` updates the existing imported source instead of creating another session.\n\nImport does not extract ZIP paths to disk. It reads Markdown entries in memory, validates ContextVault frontmatter, sanitizes generated filenames, and enforces limits of 100 MB per input archive, 10 MB per Markdown file, and 1,000 Markdown files per import.\n\n### Normalize And Index\n\nNormalize legacy and current session files into the shared `ContextSession` and `ContextEvent` model, then build a local JSON index:\n\n```bash\nnpm run vault:index\n```\n\nOutput:\n\n```text\n.contextvault/index/context-index.json\n```\n\nThe normalizer supports terminal snake_case fields such as `started_at`, `ended_at`, and `git_branch`, plus the browser export fields `platform`, `date`, and `conversation_id`. Browser `User` and `Assistant` sections become shared `user` and `agent` events with platform and role metadata.\n\n### Retrieve Relevant Context\n\nRetrieve decisions, tasks, problems, notes, and messages related to a query:\n\n```bash\nnpm run vault:retrieve -- \"auth middleware\"\n```\n\nRetrieval is local and deterministic. It ranks phrase matches, token matches, event importance, and recency without sending context to an external model or API.\n\nThe result can include browser conversations and terminal sessions in the same response.\n\n### Investigate Project Questions\n\nContextVault returns dated source evidence instead of generating an unsupported answer:\n\n```bash\n# What happened in the project during the last two weeks?\nnpm run vault:history -- --since 2w\n\n# What did Codex decide about authentication?\nnpm run vault:decisions -- auth --source codex\n\n# Show captured Redis problems from the last 30 days.\nnpm run vault:problems -- redis --since 30d\n\n# Retrieve only Codex decisions related to auth.\nnpm run vault:retrieve -- auth --type decision --source codex --since 30d\n```\n\nSupported filters:\n\n- `--type decision,task,problem,note,user,agent`\n- `--source codex`, `--source browser`, or a browser platform such as `--source chatgpt`\n- `--since 24h`, `--since 14d`, `--since 2w`, or an ISO date\n- `--limit 10`\n\nThe engine does not currently call an LLM to synthesize prose answers. `vault:prepare` packages the relevant evidence for the agent you choose.\n\n### Inspect Tasks, Decisions, And Problems\n\n```bash\nnpm run vault:tasks\nnpm run vault:decisions\nnpm run vault:problems\n```\n\nEquivalent package commands are `contextvault tasks`, `contextvault decisions`, and `contextvault problems`.\n\n### Prepare An Agent Context Package\n\nGenerate a focused context package for Codex, Claude Code, Cursor, or another AI tool:\n\n```bash\nnpm run vault:prepare -- \"auth middleware\"\n```\n\nOutput:\n\n```text\n.contextvault/exports/prepared-context.md\n```\n\nThe package contains project memory, relevant sessions, decisions, tasks, problems, notes, source metadata, and guidance for the next agent.\n\n### Maintain Project Memory\n\nRefresh the generated decisions, tasks, and problems section in `memory.md`:\n\n```bash\nnpm run vault:memory\n```\n\nManual content in `memory.md` is preserved. ContextVault only replaces its marked generated block.\n\n### Link Sessions\n\nCreate an explicit relationship between two sessions:\n\n```bash\nnpm run vault:link -- \"fixed by\"\n```\n\nLinks are stored locally in:\n\n```text\n.contextvault/links.json\n```\n\n### Generate A Timeline\n\nCreate a chronological project-context timeline:\n\n```bash\nnpm run vault:timeline\n```\n\nOutput:\n\n```text\n.contextvault/exports/context-timeline.md\n```\n\n### Engine Storage\n\n```text\n.contextvault/\n config.json\n memory.md\n links.json\n imports/\n browser/\n index/\n context-index.json\n sessions/\n exports/\n contextvault-terminal-export.md\n prepared-context.md\n context-timeline.md\n```\n\nNo backend, account, vector database, embedding API, or cloud service is required.\n\n---\n\n## Roadmap\n\n

\n \"browser\n \"terminal\n \"context\n \"future\n

\n\n### Implemented\n\n- Browser Capture\n- Terminal Capture MVP\n- Local-first browser storage\n- Local-first terminal storage\n- Markdown export\n- Browser ZIP export\n- Terminal search\n- Shared context model\n- Context normalization for terminal sessions and browser exports\n- Markdown, ZIP, and directory browser import\n- Deterministic duplicate import prevention\n- Local context index\n- Cross-surface query-based context retrieval\n- Prepared agent context packages\n- Focused task, decision, and problem views\n- Filtered project history and evidence queries by source, type, and time\n- Generated project memory block\n- Explicit session links\n- Context timeline export\n\n### In Progress\n\n- npm registry publication\n- Browser adapter hardening\n- Demo/storytelling assets\n\n### Future\n\nThe unified Context Engine now exists. The next work is hardening retrieval and adding direct adapters that emit the same shared context model without manual export/import.\n\n- Auto-tagging system\n- Draft recovery\n- Retrieval ranking improvements and optional local semantic indexing\n- Automatic context linking suggestions\n- Memory conflict and stale-task detection\n- Optional local-model or user-configured provider adapter for grounded natural-language answers\n- MCP server\n- VS Code extension\n- Claude Code integration\n- Codex integration\n- Cursor integration\n- Encrypted backups\n- Optional self-hosted sync\n\n---\n\n## Known Limitations\n\n- Provider UI changes may require selector updates.\n- Generic browser adapter is best-effort only.\n- Browser storage is local to the browser profile.\n- Terminal storage is local to the repository where `.contextvault/` is initialized.\n- Terminal capture records explicitly entered context; it does not automatically intercept every shell process.\n- Context Engine retrieval is currently lexical and deterministic; it does not use embeddings or semantic model calls.\n- Browser conversations enter the Context Engine through explicit Markdown/ZIP import; automatic synchronization from IndexedDB is not implemented.\n- The `contextvault` package binary is implemented and locally testable, but npm registry publication is a separate release action requiring npm credentials.\n- Natural-language answer generation is not built in; current commands retrieve grounded local evidence and prepare it for an agent.\n\n---\n\n## Author\n\n**Mohammad Ali Abdul Wahed**\n\n| | |\n| --- | --- |\n| GitHub | [aliabdm](https://github.com/aliabdm) |\n| Portfolio | [senior-mohammad-ali.vercel.app](https://senior-mohammad-ali.vercel.app/) |\n| Dev.to | [@maliano63717738](https://dev.to/maliano63717738) |\n| Medium | [@aliabdm](https://medium.com/@aliabdm) |\n| X (Twitter) | [@Maliano63717738](https://x.com/Maliano63717738) |\n| LinkedIn | [Mohammad Ali Abdul Wahed](https://www.linkedin.com/in/mohammad-ali-abdul-wahed-1533b9171/) |\n\n---\n\n## Philosophy\n\nContextVault is a step toward Git for Context: a portable, local-first memory layer for conversations, coding agents, project decisions, and future AI workflows.\n","readmeFilename":"README.md","_rev":"1-8424bd0c0e0e4cb895ca1ae6e30431d8"}