The Vault

The Vault

[](https://github.com/aliihsaad/the-vault/actions/workflows/release-windows.yml)

The Vault is a local-first memory operating system for AI-assisted work. It gives coding agents and human operators a durable project memory layer: decisions, handoffs, implementation summaries, task results, project relationships, and recallable context survive across sessions instead of being lost in chat history.

It ships as a TypeScript workspace with a shared core engine, command-line interface, MCP server, and Electron desktop console. Windows releases also bundle their own vault-memory MCP runtime, so installed users can connect Codex, Claude Desktop, or Claude Code without keeping the source repo on disk.

The Vault also includes an optional Graphify extension. When enabled for a project, Vault manages the Graphify runtime and artifacts, embeds Graphify's generated project graph in the desktop app, and exposes graph-aware MCP tools so agents can ask structural questions before reading large parts of a repository.

The Vault also includes an optional Vault Collab extension: a live, provider-neutral multi-agent collaboration layer with sessions, roles, handoff inboxes, launch requests, policy packs, and append-only discussions over its own separate local SQLite store (the memory engine only reads it). Agents coordinate by pulling their own inbox via a receive work-loop. New workers launch only after explicit user approval; on Windows the app can open a visible PowerShell worker window, and every approved launch still exposes a copyable command fallback.

The 60-Second Version

• AI agents forget between sessions, even when the project has a long history.
• The Vault stores project memory outside the model, on your machine.
• Agents ask the Vault MCP server for relevant context instead of reading the whole memory store.
• Graphify can add a local project graph so agents can narrow file reads through graph queries, paths, neighbors, and impact checks.
• Work can continue later from Codex, Claude Desktop, Claude Code, or another MCP client.
• Vault does not silently spawn agents; launch requests require explicit approval and use a visible terminal or copyable command fallback.
• You stay in control because memory is local, inspectable, and important cleanup changes are reviewable.

How It Feels To Use

| Without The Vault | With The Vault | | --- | --- | | Start a new AI session. | Start a new AI session. | | Re-explain the project state. | The agent recalls the current project state. | | Rediscover decisions and old bug causes. | The agent sees recent decisions, files touched, and next steps. | | Repeat handoff work manually. | The agent saves a new handoff for the next session. |

The result is not magic memory. It is a practical continuity layer: the important project facts are saved, ranked, reviewed, and reused when they are relevant.

Visual Overview

System Topology

Codex / Claude / Agent
        |
        v
Vault MCP Server
        |
        v
Vault Core
        |
        +--> Memory Store
        +--> Task Executor
        +--> Desktop Console

Cross-Agent Continuity

Codex implements change
        |
        v
Vault saves files touched, intent, decisions, next steps
        |
        v
Claude recalls context later
        |
        v
Claude reviews, debugs, or continues the work

Recall Funnel

Stored memories
        |
        v
Candidate search
        |
        v
Ranking and pruning
        |
        v
Recall pack
        |
        v
Injected into agent context

Project Hygiene

Naming drift / duplicate projects
        |
        v
Vault detects related records
        |
        v
Proposal generated
        |
        v
Human review
        |
        v
Canonical project memory

Why It Exists

AI coding sessions are productive but forgetful. The next agent often has to rediscover architecture decisions, bug causes, deployment notes, naming decisions, and unfinished work. The Vault turns that context into structured local memory that can be saved, ranked, recalled, curated, and reused by multiple clients.

The goal is not to replace a repo, issue tracker, or documentation site. The Vault fills the space between them: high-signal operational memory for ongoing work.

Who This Is For

• Developers using Codex, Claude Code, Claude Desktop, or other MCP-aware tools.
• People juggling multiple projects where decisions and handoffs get scattered.
• AI-assisted workflows that need continuity across sessions and agents.
• Local-first users who do not want memory locked inside one chat product.
• Small teams that want durable implementation context without adopting a heavy knowledge system.

Real-World Scenarios

Resume a project after days or weeks

Ask an agent to recall the project before it starts work. The Vault can surface the current phase, latest decisions, open issues, files touched, and saved next steps so the session starts from the real project state.

Switch between Codex and Claude

One agent can implement a change and save the handoff. Later, another client can recall the same project context through MCP and continue from the saved intent, decisions, and file references.

Debug with historical context

Before debugging, an agent can recall recent changes, related bug notes, prior fixes, and implementation files. That reduces time spent rediscovering what changed and why.

Keep project identity clean

Long-running AI work can create naming drift: old project names, duplicate records, or inconsistent casing. The Vault tracks canonical project decisions, detects related records, and supports reviewable merge workflows.

Use Vault while juggling multiple projects

Inactive projects stay warm. When you return, their decisions, handoffs, and next steps are still available without keeping every detail in your head or in a single chat thread.

Use Cases

• Continue feature work across Codex, Claude, and desktop sessions without re-explaining the project.
• Save implementation handoffs with exact files touched, decisions made, and next steps.
• Record canonical project decisions such as naming, architecture, release strategy, and integration rules.
• Recall relevant prior context before debugging or changing a feature.
• Maintain project identity when names drift or duplicate project records appear.
• Keep local task results, summaries, and delegated research attached to the right project.
• Inspect and curate memory through a desktop dashboard instead of raw files.
• Connect MCP clients to one shared local memory source.

What Makes It Different

The Vault is not:

• a chat history archive
• a generic notes app
• a replacement for GitHub issues or documentation
• memory locked inside one model provider
• a dump of every saved note into every prompt
• an unsupervised Codex or Claude process spawner

The Vault is:

• an external project memory layer
• local-first by default
• MCP-accessible from multiple clients
• ranked and pruned recall for agent context
• cross-agent continuity for AI-assisted work
• project lifecycle hygiene for naming drift, duplicates, and cleanup

Trust And Control

• Storage is local-first: memory files and SQLite state live on your machine.
• MCP clients receive recall packs, not the entire memory store.
• Destructive cleanup uses lifecycle states and review before final deletion.
• Client setup backs up existing config files before changing them.
• The desktop setup flow edits only Vault-owned MCP entries and leaves other client config intact.
• The desktop UI lets you inspect saved memory, file placement, activity logs, project proposals, and pending-delete flows.

Core Concepts

| Concept | Meaning | | --- | --- | | Project memory | Structured records tied to a project: decisions, sessions, plans, handoffs, artifacts, references, and summaries. | | Recall packs | Ranked, compact sets of relevant memories returned for a task or session. | | MCP clients | Tools such as Codex, Claude Desktop, and Claude Code that connect to Vault through the vault-memory MCP server. | | Agent skills | Client-facing guide files that teach agents when to recall, when to save, and how to structure memory. | | Graphify extension | Optional Vault-managed graph runtime that builds project graph artifacts, serves graph.html, and powers graph-aware recall. | | Task executor | A Vault runtime that can process queued tasks, store results, and expose task status through MCP and desktop surfaces. | | Project hygiene | Naming, relationship, duplicate, and canonical-decision workflows that keep project memory organized. | | Lifecycle states | Reversible memory states such as active, stale, archived, and pending_delete before final deletion. |

Feature Overview

| Area | What The Vault Provides | | --- | --- | | Structured memory | Saves typed records with project, subject, summary, tags, keywords, priority, status, related files, and next steps. | | Smart recall | Returns ranked memory packs using project match, keywords, tags, memory type, explicit memory UID matches, recency, promoted decisions, and related context. | | Graphify extension | Optional project graph integration that detects or installs Graphify, stores artifacts under Vault-managed paths, embeds real graph.html, and keeps the rest of Vault working when Graphify is missing or failed. | | Graph-aware recall | Combines Vault memory recall with Graphify context when a fresh or usable graph exists, while logging graph use, fallback reasons, and token-savings telemetry locally. | | Vault Collab extension | Optional live collaboration layer: provider-neutral sessions with roles, handoff inboxes, append-only discussions, lease-based ghost cleanup, policy packs, event registry, and permission-gated agent launch — surfaced in a desktop operator cockpit (Needs You plus Work / Agents / Events / Policy / Registry). Uses a separate local SQLite store and pull-based (receive) delivery. | | Desktop console | Electron app with overview, memories, projects, handoffs, decisions, loops, recall, analytics, Graphify, Vault Collab, agent runtime, settings, and inspector tabs. | | MCP integration | vault-memory MCP server for external agents and clients, including memory tools, task tools, and Vault-owned Graphify graph tools. | | One-click client setup | Desktop Settings -> Client setup can connect Codex, Claude Desktop, and Claude Code to the bundled memory runtime, add Vault Collab as a second MCP server, and install/remove the matching agent guide files. | | CLI access | Command-line entry point over the same core APIs. | | Project hygiene | Project descriptions, project listing, naming drift handling, duplicate project merging, and relationship tracking. | | Lifecycle controls | Reversible memory states such as active, stale, archived, and pending_delete before deletion. | | Task records | Queued task metadata, model routing, executor status, task results, retries, and saved summaries. | | Project momentum | Per-project week-over-week activity delta (↑/↓/inactive) shown on the Overview to make stagnating projects visible. | | Open loops panel | Aggregated unfinished work — items with non-empty next_steps plus stale debugging routines — bucketed by derived priority (high/medium/low) with snooze support via snoozed_until. | | Close-the-loop on recall | vault_recall_context returns a capped, pressure-ranked open_loops field so agents surface unfinished work back to the user. Dedicated MCP tools support single-loop resolution plus exhaustive loop audits and batch resolution. | | Local privacy | SQLite database and memory files stay on the user's machine unless the user explicitly pushes or exports them. |

Interfaces

The Vault is built around one shared core package and several thin interfaces:

• Desktop app: the primary operator UI for installed users.
• MCP server: exposes memory tools to Codex, Claude Desktop, Claude Code, and other MCP clients.
• CLI: useful for quick local checks and scripts.
• TypeScript core: reusable services for saving, recalling, ranking, project maintenance, tasks, and settings.

Screens And Workflows

The desktop app currently includes:

• Overview: local memory status, activity, recall, open loops, relationship graph, and project radar in one cockpit.
• Memories: search, filter, inspect, edit, and save structured memory items.
• Projects: searchable project directory with memory counts, descriptions, workspace signals, momentum, and delete/merge controls.
• Handoffs: filtered workspace for transfer notes and preserved next actions.
• Decisions: promoted project choices and rationale.
• Loops: open-loop control surface with project/routine/tag filtering, snooze, open, and resolve actions.
• Recall: inspect recall activity, candidate pruning, prompt packing efficiency, and compact recall logs.
• Analytics: operational charts from logs, memory state, and task queue counters.
• Graphify: choose a project source folder, build or rebuild Graphify artifacts, inspect graph freshness, open reports, and view the real Graphify graph.
• Vault Collab: operator cockpit for the optional collaboration extension — Needs You plus Work, Agents, Events, Policy, and Registry tabs. Request agents for a selected project/workspace, approve or reject launch requests, and inspect role/session state.
• Agent: inspect Vault's built-in task runtime, delegated task queue, executor events, and runtime controls.
• Settings: configure runtime behavior, lifecycle policy, Graphify and Vault Collab extension detection/install, prompt guides, model routing, and client setup.
• Inspectors: Activity, Files, and Reviews tabs for operational logs, vault files, project proposals, and pending deletes.

Operations Overview

The Overview is the daily operator surface: live local status, activity, project radar, recent relationship graph, open loops, recall trends, telemetry, and review queues.

Open Loops

The Loops page turns unfinished work into an explicit queue. Operators can filter by project, routine, and tag, inspect the selected loop, then open, snooze, or resolve it.

Recall Efficiency

Recall shows how much prompt context Vault avoided sending to the agent window: estimated tokens saved, candidate pruning, recall volume, signal strength, and a compact signal log. When Graphify is enabled, recall activity also records graph-aware context use so operators can see when the project graph is contributing to the answer path.

Graphify Project Graph

The Graph page is now Graphify-aware. Vault keeps Graphify optional, but when it is installed and enabled for a project, Vault stores graph artifacts under managed extension paths, embeds Graphify's generated graph.html, preserves the last good graph when rebuilds fail, and asks for a source folder before building projects that do not yet have one.

Vault Collab Cockpit

Vault Collab is a separate live coordination layer for multi-agent work. The desktop cockpit shows approval-needed items, routed handoffs, role-grouped sessions, policy packs, and the event registry. Launches stay permission-gated: after approval, The Vault opens a visible worker terminal on supported Windows builds or leaves a copyable command for manual launch.

Memory Bank

The Memory Bank is the main inspection surface for saved project context: search, filter, select a record, inspect metadata, and review the full saved summary without leaving the desktop console.

Install For Normal Use

For Windows users, use the GitHub Release installer:

1. Open the repository's Releases page.
2. Download The-Vault--win-x64.exe.
3. Run the installer.
4. Open The Vault.
5. Go to Settings -> Client setup.
6. Connect Codex, Claude Desktop, or Claude Code.
7. Restart the client so it launche

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aliihsaad
• Source: aliihsaad/the-vault
• License: MIT

Install and usage instructions live in the source repository linked above.