memvault

A local, OKF-compatible knowledge engine for AI agents. Capture your Codex / Claude / Gemini sessions, retrieve them with hybrid semantic + keyword search, serve them to every agent harness over MCP, visualize them as an interactive graph, and export to a portable Open Knowledge Format bundle.

What is this?

Google's Open Knowledge Format (OKF) standardized how to store agent knowledge — markdown files with YAML frontmatter. It deliberately leaves out the hard parts: retrieval, capture, serving, and enforcement.

memvault is that missing engine. Point it at a directory of markdown notes (an OKF bundle) and it becomes a living, queryable, agent-served knowledge base.

memvault produces and consumes OKF v0.1 bundles — it rides the standard, it doesn't replace it.

Related MCP server: okf-tools

See it

Every page is a node; every cross-link is an edge. Search, filter by type, switch layouts, and read any concept with its backlinks — all in one self-contained HTML file (no server):

Generated from the public demo bundle in examples/demo with memvault viz. Your own graph stays local.

Quickstart

# install (from a clone)
pip install -e .              # add ".[neural]" for real multilingual embeddings
                              # add ".[yaml]"  for robust YAML frontmatter

# point at your knowledge bundle (default: ~/llm-wiki)
export MEMVAULT_WIKI=~/llm-wiki

# 1. capture your agent conversations (Codex / Claude Code / Gemini)
memvault ingest

# 2. build the semantic index
memvault index

# 3. search (hybrid semantic + keyword)
memvault search "what did I decide about the auth refactor"

# 4. visualize -> writes viz.html you can open in any browser
memvault viz

# 5. export a portable OKF bundle
memvault export --out ./okf-bundle

# 6. serve to your agents over MCP (stdio)
memvault serve

Try it on the bundled demo with no setup:

memvault viz --wiki examples/demo --out demo.html && open demo.html

Wire it into your agents (one command)

memvault registers itself into every harness it detects — registering the MCP server and a wiki-first routing block, so your agents actually consult the wiki:

memvault install            # detect + wire (backs up every file it touches)
memvault install --check    # show wiring status
memvault install --dry-run  # preview, change nothing
memvault install --uninstall

Or register the stdio server manually anywhere MCP is supported:

{ "command": "memvault", "args": ["serve", "--wiki", "/path/to/bundle"] }

How it works

  ~/.codex  ~/.claude  ~/.gemini        markdown bundle (OKF)
        \       |        /                      |
         ▼      ▼       ▼                        ▼
   ingest (sessions) ───────────────►  raw/manifests/*.jsonl
                                               │
                              index (hashing or neural embeddings)
                                               │
        ┌──────────────┬───────────────┬───────┴────────┐
        ▼              ▼               ▼                ▼
     search        serve (MCP)       viz            export (OKF)
   hybrid RRF    every harness   interactive graph   portable bundle

• Capture — reads only visible chat turns; tool output, attachments, and credential-looking strings are skipped or scrubbed; sensitive sessions are reduced to counts. Incremental: unchanged files are not re-read.

• Retrieve — dense cosine over an embedding index fused with a lexical scorer via Reciprocal Rank Fusion. Default embedder is a dependency-free numpy hashing encoder (Korean + English, offline, deterministic); pip install ".[neural]" upgrades to a multilingual transformer automatically.

• Serve — a pure-stdlib MCP stdio server exposing wiki_answer_context, wiki_search, wiki_semantic_search, and wiki pages as memvault:// resources.

• Visualize / Export — vendored OKF viewer renders the graph; export emits a conformant OKF v0.1 bundle (frontmatter mapped, wikilinks normalized, index.md generated).

Configuration

Relationship to OKF

memvault is an independent project. It targets the Open Knowledge Format v0.1 specification published by Google Cloud, and bundles OKF's reference viewer (Apache-2.0). It is not affiliated with or endorsed by Google. See NOTICE.

License

Apache-2.0. See LICENSE.