MNEVA

AI coding memory as plain Markdown. Follows your repo, lives in git, opens in Obsidian. No account, no cloud.

Built with the tools and technologies:

English | 中文

Table of Contents

• Table of Contents
• Overview
• What you get
• Project Structure
  • Project Index
• Getting Started
  • Prerequisites
  • Installation
  • Usage
  • Testing
• Roadmap
• Contributing
• License
• Acknowledgments

Overview

Every AI memory tool keeps your memory in its own database. mneva keeps it in your files.

Records are plain Markdown with YAML frontmatter under ~/.mneva/store/. You can read them, grep them, edit them in any editor, commit them to git, and open them in Obsidian. The SQLite index is disposable — delete it and it rebuilds from the Markdown. No account to create, no cloud to sync to, no telemetry on by default.

The problem it solves: every AI assistant forgets. Open a new chat and you re-explain your project from scratch. Switch from Claude Code to Cursor and the context doesn't follow. Capture a decision once; every MCP-capable tool can read it.

Why that matters more than the storage engine: a memory you can't read is a memory you can't audit, correct, or trust. When your assistant records something wrong about your architecture, you want to open the file and fix the line — not query an opaque store and hope.

v0.2 — mneva now speaks MCP. Wire mneva-mcp into any Model Context Protocol client (Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Continue, ChatGPT Desktop in Developer Mode) in 30 seconds. The AI client supplies the intelligence; mneva supplies the memory. No API key required for the memory layer.

What you get

• 🧠 Memory that crosses tools. Capture a fact in one AI client, recall it in another. Your context stops dying inside a single chat window.
• ⚡ Zero-key, 30-second setup. The MCP memory layer needs no API key — your AI client already supplies the intelligence. One config block, restart, done.
• 🏠 Your data, on your disk. Records are plain .md files under ~/.mneva/. Read them in any editor, sync them through your own Obsidian vault, version them with git. No server, no account, no upload.
• 🔍 Search that finds the right memory. BM25 keyword ranking with optional sqlite-vec vector reranking, filtered by project scope and by how long a memory should live (transient vs permanent).
• 🔒 Private by default. mneva makes zero outbound network calls unless you opt into the advanced BYOK features. No telemetry, ever — the opt-in mneva diagnose --share is the only thing that emits anything, and it goes to your clipboard, not to us.

Before / after

Without mneva, every new session starts the same way:

"Quick context: we're on SQLite not Postgres, auth lives in auth.ts, and we already ruled out websockets…"

With mneva, you said it once. Any AI client you wire up just knows — across chats, across tools, across days.

Under the hood

• Python 3.11+, one self-contained CLI (mneva) plus an MCP server (mneva-mcp).
• MCP server built on the official mcp SDK (FastMCP), exposing six tools your AI client auto-discovers: capture_memory, search_memory, forget_memory, list_recent_memories, replay_context, get_status.
• Storage: plain Markdown + YAML frontmatter under ~/.mneva/, indexed by SQLite (WAL mode for safe concurrent access from multiple AI clients).
• Search: rank-bm25 keyword scoring with optional sqlite-vec vector reranking.
• Optional HTTP API (mneva serve, FastAPI) and BYOK providers (Anthropic / OpenAI / Google / OpenRouter) power the advanced synthesize / digest / distill commands.

Project Structure

└── mneva/
    ├── .github
    │   └── workflows
    ├── CHANGELOG.md
    ├── docs
    │   ├── alpha-onboarding.md
    │   ├── manual-smoke-m6.md
    │   └── providers.md
    ├── LICENSE
    ├── mypy.ini
    ├── pyproject.toml
    ├── pytest.ini
    ├── README.md
    ├── src
    │   └── mneva
    └── tests
        ├── __init__.py
        ├── __pycache__
        ├── conftest.py
        ├── integration
        └── unit

Project Index

Getting Started

Prerequisites

• Python 3.11 or newer
• uv (recommended). If you do not already have uv:
  • macOS / Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
  • Windows (PowerShell): irm https://astral.sh/uv/install.ps1 | iex
  • If uv is not recognized after install on Windows, close and reopen your terminal (uv writes itself to PATH at install time but the change is only picked up on a fresh shell — same gotcha pipx has).

pipx is still supported as a fallback; see Alternative installs below.

Wire mneva into your AI agent (the headline path)

Claude Code or Codex: one command.

uvx mneva setup

It registers mneva with every agent CLI it finds on your PATH (claude, codex), writes a profile template to ~/.mneva/profile-template.md, and prints the next steps. It is safe to re-run, and --dry-run shows the commands without running them.

For any other client, pick the one you use most. Paste the snippet into its MCP config and restart the client. The first time mneva-mcp launches it creates ~/.mneva/ automatically — no mneva init required.

First launch is slow, then instant. The first run downloads mneva and its dependencies (a few seconds) and caches them. If your client flags the server as slow or failed on the very first try, restart the client once — it connects from cache immediately. To pre-warm, run uvx --from mneva mneva-mcp once in a terminal and press Ctrl-C after it starts.

Claude Desktop — edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mneva": {
      "command": "uvx",
      "args": ["--from", "mneva", "mneva-mcp"],
      "env": { "MNEVA_MCP_CLIENT": "claude-desktop" }
    }
  }
}

Claude Code — edit ~/.claude.json (or run claude mcp add):

{
  "mcpServers": {
    "mneva": {
      "command": "uvx",
      "args": ["--from", "mneva", "mneva-mcp"],
      "env": { "MNEVA_MCP_CLIENT": "claude-code" }
    }
  }
}

Cursor — create ~/.cursor/mcp.json (or .cursor/mcp.json in your workspace):

{
  "mcpServers": {
    "mneva": {
      "command": "uvx",
      "args": ["--from", "mneva", "mneva-mcp"],
      "env": { "MNEVA_MCP_CLIENT": "cursor" }
    }
  }
}

Windsurf — edit ~/.codeium/windsurf/mcp_config.json with the same shape ("MNEVA_MCP_CLIENT": "windsurf").

ChatGPT Desktop — MCP support is currently behind Developer Mode (beta) in the in-app settings; enable it and add the same config block ("MNEVA_MCP_CLIENT": "chatgpt-desktop").

Cline / Continue — both honor the same Manifest, scoped to your VS Code workspace.

After restart, ask the AI client "remember that we decided X" and watch mneva append a record. Search it next session.

Try it from the command line

The CLI is the lower-level surface — useful for scripting and for use cases where you don't have an MCP client.

uvx mneva init
uvx mneva capture --scope my-project --lifespan permanent \
    "decision: use SQLite over Postgres for v0 because zero-ops"
uvx mneva search "SQLite"
uvx mneva replay --tool=claude-code --scope=my-project

Because the Markdown is the source of truth, you can edit ~/.mneva/store/*.md in any editor and then bring the index back in line:

uvx mneva reindex   # rebuild the search index from the Markdown files

The index is disposable — delete ~/.mneva/mneva.sqlite, run reindex, and nothing is lost.

Memories that follow your repo

Capture inside a git repository and the memory records where it came from — repo, branch, and commit — right in the note's frontmatter:

scope: my-project
lifespan: permanent
repo: github.com/mneva-ai/mneva
branch: main
commit_sha: cd6d7af1c3a2982810799d2f023a028fc361c6dc

mneva search then scopes to the repo you're standing in:

uvx mneva search "SQLite"              # this repo (plus memories tied to none)
uvx mneva search "SQLite" --all-repos  # everything
uvx mneva capture --scope p --no-git "…"  # don't record provenance at all

repo comes from the remote URL, normalized — so it keeps matching after you clone the project to another machine or a different directory. Memories captured outside a repo are never hidden; only memories belonging to a different repo are filtered out.

Nothing here is required: no git, no repo, no remote. Each one just degrades to "no provenance" and capture works exactly as before.

Using mneva from a browser chat UI

The MCP path covers desktop AI clients. Browser-only AI chat UIs (claude.ai web, chatgpt.com, gemini.google.com, chat.deepseek.com) cannot speak MCP because browsers do not allow web pages to spawn local processes. The workaround is:

CLI manual workflow:

1. uvx mneva capture --scope myproj "..." after an interesting decision in chat.
2. uvx mneva search "topic" before asking a new AI a follow-up.
3. Copy matching records from terminal output into the new chat as context.

Your profile in one paste: save who you are and how you work as records with --scope profile --lifespan permanent, then run uvx mneva brief --copy and paste it into the tool's "about you" setting (for ChatGPT's custom instructions, add --max-chars 1500). mneva remembers every copy and tells you when your profile changes after it.

Alternative installs

• pipx install mneva — still supported. Existing v0.1.x users running pipx upgrade mneva get both mneva and mneva-mcp console scripts.
• uv tool install mneva + uv tool upgrade mneva — preferred over bare uvx mneva when you want a single pinned install that you upgrade explicitly (uvx resolves on first run and caches; uvx mneva@latest forces a fresh resolve).
• From source: git clone https://github.com/mneva-ai/mneva.git && cd mneva && pip install -e ".[dev]".

Updating mneva

mneva upgrade

mneva upgrade detects how mneva was installed (pipx / uv tool / uvx / pip) and runs the matching update command, so you don't have to remember which one you used. Pass --dry-run to print the command without running it. If you run the MCP server via uvx --from mneva mneva-mcp, uvx already fetches the latest published version on each run, so there is nothing to upgrade.

Advanced — BYOK LLM features

mneva synthesize, mneva digest, and mneva distill use an external LLM provider for summarization and record extraction. They require a key in your environment (Anthropic / OpenAI / Google / OpenRouter — pick one). These are power-user features, not part of the headline MCP path.

• mneva synthesize --scope X --backend anthropic — two-stage Stage 1 / Stage 2 brainstorming over a scope.
• mneva digest --scope X --backend anthropic --write-bootstrap — distills a scope into a bootstrap.md you can paste into a new tool session.
• mneva distill --source path/to/transcript.md --scope X — extracts permanent records from a raw conversation transcript. Cost-gated; pass --yes to skip the prompt.

See docs/providers.md for per-provider setup.

Observability (opt-in)

mneva diagnose [--share] prints a sanitized status report (platform, Python version, record counts by lifespan, configured backends, per-MCP-client attribution counts, last activity timestamp). The output goes to stdout only — mneva never sends it anywhere. Run it and paste the result into a bug report when something looks off.

Testing

Tests use pytest with pytest-asyncio and pytest-cov. From a source checkout with dev extras installed:

pytest

CI runs the full matrix (ubuntu / macos / windows × Python 3.11 / 3.12 / 3.13 / 3.14) on every PR via .github/workflows/ci.yml.

Roadmap

mneva is in alpha. v0.2 ships the MCP layer plus uvx-first install. Milestones:

• v0.1.0 — CLI + store + BM25/sqlite-vec index + replay templates + HTTP API + four-provider BYOK
• v0.1.x — Gap fixes, Obsidian vault read-write integration, mneva distill, CI matrix forward-defense
• v0.2 — MCP server (mneva-mcp console script + 6 FastMCP tools), uvx-first install, WAL concurrency for cross-process safety, opt-in mneva diagnose --share observability
• v0.3: git-aware memories (repo, branch, commit), mneva brief for tools without MCP, mneva setup to connect Claude Code and Codex in one command
• Later: Browser extension (Chrome / Firefox / Edge, Manifest V3) so chat UIs that cannot spawn MCP subprocesses (chatgpt.com, claude.ai web, gemini.google.com, DeepSeek) still see mneva. Entry condition: ≥10 real users + ≥3 explicit asks via mneva diagnose --share.
• v1+ — Native GUI installer for non-technical users; optional hosted mneva.app SaaS for phone / multi-device sync.

Contributing

• 💬 Join the Discussions: Share your insights, provide feedback, or ask questions.
• 🐛 Report Issues: Submit bugs found or log feature requests for the mneva project.
• 💡 Submit Pull Requests: Review open PRs, and submit your own PRs.

License

Mneva is licensed under the Apache License 2.0.

Links

• Website: https://mneva.org
• Repository: https://github.com/mneva-ai/mneva
• PyPI: https://pypi.org/project/mneva/
• Issues: https://github.com/mneva-ai/mneva/issues
• Changelog: CHANGELOG.md