mneva 0.1.3

Persistent agent context substrate. Local-first CLI.

MNEVA

Persistent agent context substrate. Local-first markdown store that every AI tool can query.

Built with the tools and technologies:

---

Table of Contents

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

---

Overview

mneva is a local-first persistent context substrate for AI-assisted development. It captures, indexes, and replays your project's insights, decisions, and history across sessions, ensuring your AI tools never start from a blank slate.

Why mneva?

This project eliminates session amnesia for AI agents and developers by providing a durable, searchable memory layer that runs entirely on your machine. The core features include:

• 🏠 Local-First Context Store: All data persists in ~/.mneva as structured markdown. Your team's knowledge stays private, offline, and under your control.
• 🔍 Hybrid Semantic Search: Instantly surface relevant context using BM25 keyword matching combined with optional sqlite-vec vector reranking, filtered by scope and lifespan.
• 🧩 Multi-Provider AI Engine: Seamlessly swap between Anthropic, OpenAI, Google, or OpenRouter for synthesis and brainstorming, avoiding vendor lock-in.
• 🔄 Context Replay for AI Tools: Generate structured prompt blocks that inject captured context directly into your AI coding sessions, cutting out repetitive explanations.
• 🖥️ Dual CLI & API Interface: Manage your memory interactively via mneva capture/search/replay commands, or integrate it into automated pipelines using the built-in FastAPI server.

---

Features

	Component	Details
⚙️	Architecture	FastAPI web service with Uvicorn ASGI server Async/await design for non‑blocking I/O RAG‑like pipeline: BM25 keyword ranking + sqlite‑vec vector similarity CLI interface via Click (inferred from dependency) Modular router structure for separate AI provider endpoints
🔩	Code Quality	Static type checking with mypy (config in mypy.ini) Linting + formatting with ruff Code coverage enforced via pytest‑cov CI workflow (ci.yml) runs lint, type‑check, and tests Packaging verified via install-verify.yml
📄	Documentation	Apache 2.0 License (see LICENSE) User docs in docs/: alpha-onboarding.md, providers.md Inline docstrings on all public CLI commands and API endpoints
🔌	Integrations	OpenAI (GPT models) Anthropic (Claude models) Google Generative AI (Gemini) rank‑bm25 for keyword retrieval sqlite‑vec for vector storage & similarity search python‑frontmatter (YAML/JSON metadata parsing)
🧩	Modularity	Separate provider modules per AI service Configuration split across pyproject.toml, mypy.ini, pytest.ini, and CI YAML files Clear dev‑vs‑prod dependency groups (testing, linting, packaging) Router‑based FastAPI app structure (common pattern)
🧪	Testing	pytest as test runner with pytest‑asyncio for async tests pytest‑cov for coverage measurement CI pipeline (ci.yml) executes tests on each push Installation verification workflow ensures package builds correctly
⚡️	Performance	Async request handling via Uvicorn and FastAPI sqlite‑vec provides fast approximate nearest neighbor search rank‑bm25 delivers efficient keyword scoring No explicit benchmark data; performance limited by single‑node SQLite
🛡️	Security	API keys for AI providers expected via environment variables (standard practice) No injection/flaw detection tools visible (e.g., Bandit) httpx uses HTTPS for outbound calls Secrets handling not explicitly enforced in CI
📦	Dependencies	Runtime: fastapi, uvicorn, click, httpx, openai, anthropic, google‑generativeai, rank‑bm25, sqlite‑vec, python‑frontmatter Dev: pytest, pytest‑asyncio, pytest‑cov, ruff, mypy, twine, build

---

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

mneva/

__root__

⦿ __root__

File Name	Summary
LICENSE	- Defines the legal terms for using, modifying, and distributing the project under the Apache License 2.0, granting copyright and patent permissions, outlining contribution submission, and disclaiming warranties - This permissive license fosters open collaboration and community adoption while protecting both the copyright holder and users from liability - It is the foundational governance for all project code.
mypy.ini	- Configures strict static type checking for the projects core source code, enforcing Python 3.11 standards and ensuring type consistency while gracefully handling third-party libraries with missing annotations - Maintains code quality and reduces runtime errors across the architecture.
pyproject.toml	- Configures the Mneva project as a Python package for a persistent agent context substrate and local-first CLI - It declares dependencies for the server, CLI, LLM integrations, and search components - It also sets up the CLI entry point and development tooling, ensuring proper packaging and distribution of the application.
pytest.ini	- Configures pytest’s test discovery in the tests directory, adds command-line flags for concise reporting, defines an integration marker for filesystem and HTTP end-to-end tests, and enables asyncio mode - This standardizes how the project runs its unit and integration tests, ensuring consistent behavior across the codebase.

.github

⦿ .github

workflows

⦿ .github.workflows

File Name	Summary
ci.yml	Automates continuous integration across multiple operating systems and Python versions, ensuring code quality through linting, type-checking, testing with coverage thresholds, and verifying the built wheel has no duplicate entries before installing and running a version smoke test.
install-verify.yml	- Automates post-release validation by installing the mneva package across multiple operating systems and Python versions using pipx, then confirming a successful installation with a version check - This ensures the released package is functional and accessible, integral to the projects continuous integration and delivery pipeline.

src

⦿ src

mneva

⦿ src.mneva

File Name	Summary
api.py	- Defines the FastAPI web application exposing endpoints for capturing, forgetting, searching, and replaying records - Integrates authentication via token middleware, coordinates with the indexer for search, store for persistence, and replay module for output - Provides the primary HTTP interface through which external tools interact with the Mneva knowledge base.
cli.py	- Defines the command-line interface for the mneva persistent agent context substrate using Click - It exposes commands to initialize the data root, capture and search records, generate context replays for various AI coding tools, start a local API server, and perform two-stage synthesis or bootstrap digest consolidation - This module acts as the primary user-facing entry point.
config.py	- Manages application configuration by defining a frozen dataclass for settings like API token and embedding provider, and provides utilities to persist and load configuration from a JSON file - This centralizes configuration handling, ensuring consistent access to runtime parameters across the entire codebase.
indexer.py	- Implements a hybrid search index that combines BM25 ranking with optional sqlite-vec re-ranking for querying stored records - Manages record insertion, deletion, and retrieval with filtering by scope and lifespan - Supports both full-text and vector-powered search modes, returning the top-k relevant records for a given query.
paths.py	- Manages the applications home directory by respecting the $MNEVA_HOME environment variable or defaulting to ~/.mneva - Ensures the root and required subdirectories (store, index, adr, templates) exist, creating them idempotently - This foundational module enables consistent data storage and retrieval across the entire codebase.
replay.py	- Generates context replay blocks for supported tools by combining template bodies with captured permanent records, optionally filtered by scope - Serves as shared logic used by both the mneva replay CLI command and the GET /replay HTTP endpoint, ensuring consistent output formatting across interfaces.
store.py	- Persists and retrieves structured records as markdown files with frontmatter metadata, serving as the data access layer for the projects file-based store - It handles serialization and provides create, read, update, delete, and iteration operations, abstracting file system details from the rest of the codebase.
synth.py	- Implements a two-stage brainstorming and critical analysis pipeline using captured context records, along with a digest generator for producing L1 bootstrap summaries - All large language model calls are routed through the Provider protocol, keeping the module provider-agnostic and enabling testable orchestration of the full workflow from context dump to final output.

providers

⦿ src.mneva.providers

File Name	Summary
anthropic.py	- Enables prompt-driven text completions through Anthropics API, using a default large-context model - Handles authentication by checking for an API key in environment variables and raises an error if missing - This provider supports the systems extensible architecture by abstracting Anthropic as one of multiple possible AI backends.
base.py	- Defines the Provider protocol and error classes that form the foundation for all LLM adapter implementations - Providers implement a one-shot non-streaming complete method, relying solely on environment variables for API keys - MissingAPIKeyError enforces secure key management, while ProviderError serves as a catch-all for provider-side failures.
google.py	- Configures the Google Generative AI provider as part of the provider abstraction layer, defaulting to the gemini-2.0-pro model with 1M-token context window - It retrieves the API key from environment variables and exposes a completion interface for generating text responses, seamlessly integrating into the mneva ecosystem for multi-provider support.
openai.py	- Provides integration with OpenAIs GPT-5 model as the default provider for completions - Handles API key authentication from environment variables and offers a simple interface to generate text responses - This enables the mneva system to leverage OpenAIs large language models for various tasks.
openrouter.py	- Provides OpenRouter integration by wrapping the OpenAI client with a customized base URL and default model, enabling the application to use a wide range of LLMs through OpenRouters unified API - The model is configurable via environment variable, and it validates the API key at initialization, raising a helpful error if missing - Its role in the provider pattern ensures a consistent interface for completion tasks across different backends.

---

Getting Started

Prerequisites

• Python 3.11 or newer
• pipx (pip install --user pipx && python -m pipx ensurepath, then reopen your terminal)

Installation

Install the latest release from PyPI:

pipx install mneva
mneva --version

Alternative without pipx: pip install --user mneva. This installs into your user site-packages and may conflict with pinned dependencies of other tools, so pipx is preferred.

To install from source (development):

git clone https://github.com/mneva-ai/mneva.git
cd mneva
pip install -e ".[dev]"

Usage

Initialize the store, capture a record, and replay it into your AI tool:

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

The full walkthrough is in docs/alpha-onboarding.md. Per-tool wiring (Claude Code → CLAUDE.md, Cursor → .cursor/rules/mneva.mdc, Codex → AGENTS.md) is covered there as well.

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) on every PR via .github/workflows/ci.yml.

---

Roadmap

Mneva is in alpha (v0.1.0). The CLI, store, indexer, replay templates, and HTTP API are all working. The next milestones, drawn from the known limitations in CHANGELOG.md:

• v0.1.0 — CLI + store + BM25/sqlite-vec index + replay templates + HTTP API + four-provider BYOK
• v0.1.x — Stability fixes, docs polish, expanded CI matrix (Python 3.14)
• v1 — MCP server endpoint, auto-distillation of long scopes
• v2 — Opt-in cloud sync (single-user → small-team)

---

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.

Contributing Guidelines

1. Fork the Repository: Start by forking the project repository to your GitHub account.
2. Clone Locally: Clone the forked repository to your local machine using a git client.

   git clone https://github.com/mneva-ai/mneva.git
   

3. Create a New Branch: Always work on a new branch, giving it a descriptive name.

   git checkout -b new-feature-x
   

4. Make Your Changes: Develop and test your changes locally.
5. Commit Your Changes: Commit with a clear message describing your updates.

   git commit -m 'Implemented new feature x.'
   

6. Push to GitHub: Push the changes to your forked repository.

   git push origin new-feature-x
   

7. Submit a Pull Request: Create a PR against the original project repository. Clearly describe the changes and their motivations.
8. Review: Once your PR is reviewed and approved, it will be merged into the main branch. Congratulations on your contribution!

Contributor Graph

---

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

---