# Memoryvault Kit > A personal memory layer for your AI tools. Intelligent authoring (gap detection, self-enriching graph, session-synthesis loop) + measurably good retrieval (94.9% blind Cov@10, sub-ms latency). Domain-agnostic framework — works for any context you want to track. MCP-native, Claude-Code-first, works with Cursor/Continue/Cline/OpenAI/Gemini. - **Type:** MCP server - **Install:** `agentstack add mcp-ayushmall-memoryvault-kit` - **Verified:** Pending review - **Seller:** [ayushmall](https://agentstack.voostack.com/s/ayushmall) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [ayushmall](https://github.com/ayushmall) - **Source:** https://github.com/ayushmall/memoryvault-kit - **Website:** https://github.com/ayushmall/memoryvault-kit#try-it-in-60-seconds ## Install ```sh agentstack add mcp-ayushmall-memoryvault-kit ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # memoryvault-kit A memory layer for the AI tools you actually use. Your professional life is scattered across calendar, gmail, slack, linear, notion, github, granola, drive. Every time you start a fresh Claude or Cursor session, you re-explain your world from zero. This kit pulls from all those places, writes what it finds as plain markdown on your laptop, and lets any AI tool query it through MCP. The vault gets richer the more you use it, because every conversation can write back. Runs on your filesystem. No cloud, no database, no vendor. MIT licensed. ## What it actually is A folder of markdown files. One file per memory, one per entity (person, project, customer, team, whatever). You can open it in Obsidian, grep it from a terminal, or talk to it from Claude Code, Cursor, Continue, OpenAI's Agents SDK, Gemini, anything that speaks MCP. ``` your sources your vault your AI tools ───────────── ────────────── ────────────── calendar memories/ Claude Code gmail ──ingest─▶ mem_*.md ──MCP──▶ Cursor slack entities/ Continue linear people/*.md OpenAI SDK notion products/*.md Gemini github teams/*.md or the memory CLI granola drive (Obsidian-readable) ``` Two loops keep it alive. One pulls fresh data from your sources every morning. The other watches for things you asked about that the vault couldn't answer well, and fills those gaps later. ## Why I built it I'm a PM. My day-to-day context lives in nine tools and every AI assistant I use sees none of it. So I started writing important things down in a notes folder. Then I wanted Claude to read them. Then I wanted it to read the right ones automatically. Then I wanted it to notice when it didn't have the right ones and fix that. This is what came out. It's domain-agnostic. PM context was my use case but the structure works for engineering leadership, sales, customer success, recruiting, investing, research, or anything else where you have entities you care about and sources where they show up. ## Sixty seconds to try it ```bash git clone https://github.com/ayushmall/memoryvault-kit.git cd memoryvault-kit python3 -m venv .venv && source .venv/bin/activate pip install -e . export MEMORYVAULT_ROOT=$(pwd)/examples/tiny_vault memory version memory ask "What does Acme need before they can go to production?" ``` The example vault has 10 memories about two fictional customers. You should see the kit pull up the right one (SSO and audit logs are the blockers). ## Five minutes to point it at your own life The intended path is Claude Code with the kit installed as a plugin. Two commands from your terminal: ```bash # 1. Clone the repo somewhere (anywhere — the path doesn't matter, # it just has to exist) git clone https://github.com/ayushmall/memoryvault-kit ~/memoryvault-kit # 2. Register it with Claude Code (the second arg is the path you cloned to) claude plugin marketplace add ~/memoryvault-kit claude plugin install memoryvault-kit@memoryvault-kit ``` `~/memoryvault-kit` is whatever path you cloned to in step 1. Claude Code reads the plugin manifest from `/.claude-plugin/` and registers everything. After running both commands, restart Claude Code once so it picks up the new MCP server. That registers all 18 skills, the `memoryvault` MCP server, and the slash commands. Then in any Claude Code session, type `/memory-setup` (or "set up memoryvault" and the skill should fire). It asks what sources you have, scaffolds the vault, generates an eval set from your real context, and walks you through your first ingest. To keep the vault fresh, you re-invoke `/memory-refresh` whenever you want — there are no background routines (they were removed; see "How authoring works" below). **Using Cowork (cloud) instead of local Claude Code?** Cowork can't access local files or your installed plugins, so the local-plugin path above doesn't apply. The kit ships a separate skill, `memoryvault-cowork`, that uses Google Drive as the vault substrate. Drop it into your Cowork session as a skill and follow its prompts. The retrieval quality is lower than the local kit (Drive search vs BM25+graph) but it works without a local install. The eventual fix — a small local `memory bridge` that exposes the full kit to Cowork over HTTP — is sketched in [`docs/architecture-bridge.md`](docs/architecture-bridge.md) but not yet shipped. After setup, every recurring update happens through `/memory-refresh` — invoke it whenever you want fresh data. Claude reads your connected source MCPs (Slack, Linear, Notion, etc.), pulls deltas, writes memories, heals the graph, runs a quick eval. ### Why the agent does the source-pulling Most sources (Notion, Linear, Slack, Gmail, Granola, Drive, Pylon, Calendar) live behind MCP servers that hold your auth. The agent is what calls those MCP tools, gets the page/issue/thread back, decides if it's substantive enough to save, synthesizes a fact-carrying title, and writes the memory. The kit ships Python writers that take pre-fetched data and turn it into properly-shaped memory files, but the fetching itself is agent-driven because that's where the auth + judgment live. Two sources are exceptions: - **GitHub PRs** — the kit shells out to `gh pr list`, no agent needed. Run `python3 -m memoryvault_kit.ingest.code_repo --repo acme/api --prs --apply` directly. - **Claude Code memory** — the kit reads `~/.claude/projects/*/memory/*.md` from disk. Run `python3 -m memoryvault_kit.ingest.claude_memory --apply` directly. For everything else, the right command is "in a Claude Code session with /memory-refresh, ask the kit to pull from Notion / Linear / etc." That's not a workaround, it's the design — agents are the bridge between MCP-gated source data and the markdown vault. ### You probably don't need to know about the CLI For day-to-day use, `/memory-setup` and `/memory-refresh` cover everything. The slash commands call the CLI internally — `/memory-refresh` runs `memory migrate --apply --quick` (heal), `memory eval --soft` (eval), and the per-source ingest modules under the hood. You shouldn't need to touch any of this. The CLI exists for two cases: - **CI / scripts** — if you ever want to run a check from a non-Claude shell (cron-on-a-server, GitHub Actions on a vault repo), `memory eval --soft --json` and `memory doctor --json` give you machine-readable output. - **Debugging** — when something looks wrong and you want to bypass the agent layer to isolate the issue. `memory doctor` is the first stop; `memory migrate --apply --quick` rebuilds the alias map. ```bash memory eval --soft # retrieval coverage number memory doctor # vault health check memory migrate --apply --quick # rebuild alias map + heal links memory eval # the three-pillar suite (slower) ``` If you don't have any notes yet, run `/memory-setup` — that's the right entry point. The CLI's `python3 -m memoryvault_kit.setup` exists as an escape hatch only. ## How retrieval works When you ask the vault a question, it does this: 1. Tokenize the query (stopwords out, version strings and numbers kept). 2. Score every memory with BM25. 3. If the query matches a known entity name verbatim, short-circuit to that entity's graph and sort by recency. 4. Otherwise walk the top BM25 seeds out to memories that share distinctive entities, follow `related:` edges, and add memories that wikilink to entities the question mentioned. 5. Return the top K. That's it. There's no embedding model, no LLM in the retrieval path, no GPU. Median latency is under a millisecond. I tried embeddings (MiniLM and BGE-small) and a cross-encoder reranker. On this vault, embeddings lost to BM25 by 20+ points. The reranker looked great on the training set and lost 2.5 points on a held-out blind set, which is the classic overfit signal. Both stay in the code as opt-in for people with very different vaults, but they're not the default. The full back-and-forth lives in `docs/eval-playbook.md`. The headline is: every variant where the LLM touched the ranker regressed. Intelligence sits at capture time (writing better memories) and consume time (reasoning over what comes back), not inside the search. ## How authoring works The vault writes itself in two ways, and **both happen in a session you're in** — not on background cron. The kit's source MCPs (Slack, Linear, Notion, Gmail, Granola, GitHub, GDrive, Pylon, …) need interactive auth and per-tool permission grants that background routines can't reliably get. So the model is: **user-present `/memory-refresh`**, however often you want it. **When you run `/memory-refresh`.** One slash command reads the sources you've connected, pulls deltas since the last refresh, writes one memory per substantive thing, then heals the graph + runs a fast soft eval. Each source has its own logic. Linear pulls issues by team and uses state-change as the event date. GitHub maps PRs to product entities by file path. Granola clusters recurring meetings into series. Slack runs per channel, classifies thread types, and writes a digest. Notion searches your pinned topics. Calendar pulls events with two-plus attendees. Gmail filters noise and synthesizes a real title from the body. Run it once a morning, or once a week, or trigger with `/loop 6h /memory-refresh` if you want it to keep going while you're in a Claude Code session. **On the fly.** When you ask the vault something and the answer is thin, the consuming agent (Claude, whichever) is told to reach back into the source MCPs you have, fetch what's missing, answer the question, and write the new finding back as a memory. So the next time you or anyone asks something similar, the vault has it. There's a coverage step inside `/memory-refresh` that watches the graph for structural holes (customer without a champion, project without an owner, hub entity with no decisions) and surfaces them as `mem_GAP_*` memories. The next session that has context on one of those gaps can fill it through `memory_update`. Failed queries also become gap memories, so the vault literally remembers what it failed to answer. > **No scheduled routines.** Earlier versions of the kit shipped 5 cron-wrapper skills (`memory-schedule`, `memory-heal-agent`, `memory-coverage-agent`, `memory-eval-runner`, `memory-authoring-cycle`). They've been removed: routines failed in practice because source-MCP auth needs a human, tokens expired, permissions weren't pre-granted, and the routines silently no-op'd. Everything they did is now folded INTO `/memory-refresh` (heal chain → coverage scan → queue drain → soft eval). One command, you in the loop. Use `/loop 6h /memory-refresh` inside a Claude Code session if you want repeat passes. ## How it stays useful Three numbers, one command: ```bash memory eval ``` - `fill_quality` is a 0-1 score for how well memories are written (entities linked, dates exact, decisions named, etc.) - `pollution_rate` is the fraction of wikilinks that are peripheral mentions rather than structural participants - `consistency` checks that the lean retrieval tier returns a strict subset of what the full tier returns, so switching tiers doesn't change behavior unpredictably `/memory-refresh` runs the soft eval (`memory eval --soft`) inline at the end of every refresh so you see retrieval health each time you run it. The fuller three-pillar `memory eval` is on-demand — run when you suspect quality has shifted. The heal chain (rebuild alias map, connect entities, split mentions, in-degree) is also folded into every `/memory-refresh`, so a single user-present invocation does the lot. If retrieval quality drops, there's a playbook at `docs/eval-playbook.md` that lists the structural things to check before tuning anything. `memory doctor --eval-recovery` walks the same checks on demand. ### Eval strategies, in plain English | Tool | What it does | When to use | |---|---|---| | `memory eval` | Three-pillar score (fill_quality + pollution + consistency) | Weekly, regression check | | `memory eval --soft` | Coverage: % of questions returning ≥2 results scoring ≥5. No gold annotations required | During `/memory-refresh`, fast | | `memory eval init --from-vault` | Generate a starter eval set from your actual vault content | Day 0, after first ingest | | `memory doctor --eval-recovery` | 5 structural checks before the eval runs | Before you blame the retriever | | `memory doctor --signal-quality` | Per-source ingest-vs-retrieval noise ratio | Weekly, finds noisy sources | | `/memory-graph-audit` | Walks you through Obsidian's graph view to catch what code can't see | Weekly visual pass | | `evals/retrieval/retrievers/*.py` | Run a specific retriever variant against the 482-Q hardened set | When you're testing a retrieval change | The combination matters. Soft coverage is fast but shallow. Three-pillar is rigorous but takes time. Doctor checks are structural. Graph audit is visual. Use them together — each catches things the others miss. ### The dashboard `memoryvault_kit/dashboard/build.py` generates a self-contained HTML page showing eval scores over time, audit history, and per-bucket retrieval performance. Open it in any browser. Useful when you want trend lines, not just the latest number. ### Tuning without editing code If `memory eval` shows a weakness in some bucket and you want to try a fix, you have two paths: **Config knobs first.** Copy `.mvkit/retrieval_config.example.json` to `.mvkit/retrieval_config.json` and edit. The retrieval modules read from there with fallbacks to code defaults. You can adjust BM25 weights, graph-walk boosts, the D7 canonical-first sort, soft-coverage thresholds, or switch retriever variants — all without touching Python. Re-run `memory eval` to see the effect. **Code edits when the algorithm needs to change.** If the knob you need doesn't exist, the algorithm itself needs the change. Edit `memoryvault_kit/retrieval/*.py` directly. The kit's code is on your filesystem, you own it. Re-run eval to verify the change helped. The split: config for tuning, code for new logic. Both stay local — neither gets committed to the public repo unless you fork. ## Running Claude Code from the vault directory You can run Claude Code from anywhere — the MCP server reads `MEMORYVAULT_ROOT` to find your vault regardless. But there's a useful option: **launch Claude Code with `cwd = $MEMORYVAULT_ROOT`**. Then Claude has direct read/write access to your memory files via its Read/Edit/Write tools, on top of the MCP layer. What this enables: - You can ask "fix the typo in mem_INGEST_LINEAR_xxx" and Claude edits the file directly - You can ask "show me all my customer entities" and Claude can `ls entities/companies/` instead of going through `memory_search_entity` - The session naturally feels like working IN your vault, not THROUGH a tool The MCP layer still works (memory_ask, memory_save, etc.) — direct file access is additive. If you don't need it, just don't launch from the vault dir. ```bash cd ~/MemoryVault claude # or: cursor . / continue ``` ## Working with other AI clients Claude Code is the primary target because that's where skills are richest. Everything else gets the same vault access through MCP, with the differences mostly in how skills translate. In Cursor, add the kit's MCP server to `~/.cursor/mcp.json`. Skills don't auto-load there, so paste `skills/memory-use/SKILL.md` into the Rules for AI section. Re-run the refresh manually in each session (background cron has the same permission-grant problems everywhere — user-present is the safe default). In Continue or Cline, register the MCP server in their config. They don't have a skill system, so rely on the tool descriptions the kit ships (they're written for exactly this … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [ayushmall](https://github.com/ayushmall) - **Source:** [ayushmall/memoryvault-kit](https://github.com/ayushmall/memoryvault-kit) - **License:** MIT - **Homepage:** https://github.com/ayushmall/memoryvault-kit#try-it-in-60-seconds Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** yes *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-ayushmall-memoryvault-kit - Seller: https://agentstack.voostack.com/s/ayushmall - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.