Metadata-Version: 2.4
Name: mneva
Version: 0.2.1
Summary: Persistent agent context substrate. Local-first CLI.
Project-URL: Homepage, https://github.com/mneva-ai/mneva
Project-URL: Repository, https://github.com/mneva-ai/mneva
Project-URL: Issues, https://github.com/mneva-ai/mneva/issues
Author-email: Nick Chen <mingxuanus@gmail.com>
License:                                  Apache License
                                   Version 2.0, January 2004
                                http://www.apache.org/licenses/
        
           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
        
           1. Definitions.
        
              "License" shall mean the terms and conditions for use, reproduction,
              and distribution as defined by Sections 1 through 9 of this document.
        
              "Licensor" shall mean the copyright owner or entity authorized by
              the copyright owner that is granting the License.
        
              "Legal Entity" shall mean the union of the acting entity and all
              other entities that control, are controlled by, or are under common
              control with that entity. For the purposes of this definition,
              "control" means (i) the power, direct or indirect, to cause the
              direction or management of such entity, whether by contract or
              otherwise, or (ii) ownership of fifty percent (50%) or more of the
              outstanding shares, or (iii) beneficial ownership of such entity.
        
              "You" (or "Your") shall mean an individual or Legal Entity
              exercising permissions granted by this License.
        
              "Source" form shall mean the preferred form for making modifications,
              including but not limited to software source code, documentation
              source, and configuration files.
        
              "Object" form shall mean any form resulting from mechanical
              transformation or translation of a Source form, including but
              not limited to compiled object code, generated documentation,
              and conversions to other media types.
        
              "Work" shall mean the work of authorship, whether in Source or
              Object form, made available under the License, as indicated by a
              copyright notice that is included in or attached to the work
              (an example is provided in the Appendix below).
        
              "Derivative Works" shall mean any work, whether in Source or Object
              form, that is based on (or derived from) the Work and for which the
              editorial revisions, annotations, elaborations, or other modifications
              represent, as a whole, an original work of authorship. For the purposes
              of this License, Derivative Works shall not include works that remain
              separable from, or merely link (or bind by name) to the interfaces of,
              the Work and Derivative Works thereof.
        
              "Contribution" shall mean any work of authorship, including
              the original version of the Work and any modifications or additions
              to that Work or Derivative Works thereof, that is intentionally
              submitted to Licensor for inclusion in the Work by the copyright owner
              or by an individual or Legal Entity authorized to submit on behalf of
              the copyright owner. For the purposes of this definition, "submitted"
              means any form of electronic, verbal, or written communication sent
              to the Licensor or its representatives, including but not limited to
              communication on electronic mailing lists, source code control systems,
              and issue tracking systems that are managed by, or on behalf of, the
              Licensor for the purpose of discussing and improving the Work, but
              excluding communication that is conspicuously marked or otherwise
              designated in writing by the copyright owner as "Not a Contribution."
        
              "Contributor" shall mean Licensor and any individual or Legal Entity
              on behalf of whom a Contribution has been received by Licensor and
              subsequently incorporated within the Work.
        
           2. Grant of Copyright License. Subject to the terms and conditions of
              this License, each Contributor hereby grants to You a perpetual,
              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
              copyright license to reproduce, prepare Derivative Works of,
              publicly display, publicly perform, sublicense, and distribute the
              Work and such Derivative Works in Source or Object form.
        
           3. Grant of Patent License. Subject to the terms and conditions of
              this License, each Contributor hereby grants to You a perpetual,
              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
              (except as stated in this section) patent license to make, have made,
              use, offer to sell, sell, import, and otherwise transfer the Work,
              where such license applies only to those patent claims licensable
              by such Contributor that are necessarily infringed by their
              Contribution(s) alone or by combination of their Contribution(s)
              with the Work to which such Contribution(s) was submitted. If You
              institute patent litigation against any entity (including a
              cross-claim or counterclaim in a lawsuit) alleging that the Work
              or a Contribution incorporated within the Work constitutes direct
              or contributory patent infringement, then any patent licenses
              granted to You under this License for that Work shall terminate
              as of the date such litigation is filed.
        
           4. Redistribution. You may reproduce and distribute copies of the
              Work or Derivative Works thereof in any medium, with or without
              modifications, and in Source or Object form, provided that You
              meet the following conditions:
        
              (a) You must give any other recipients of the Work or
                  Derivative Works a copy of this License; and
        
              (b) You must cause any modified files to carry prominent notices
                  stating that You changed the files; and
        
              (c) You must retain, in the Source form of any Derivative Works
                  that You distribute, all copyright, patent, trademark, and
                  attribution notices from the Source form of the Work,
                  excluding those notices that do not pertain to any part of
                  the Derivative Works; and
        
              (d) If the Work includes a "NOTICE" text file as part of its
                  distribution, then any Derivative Works that You distribute must
                  include a readable copy of the attribution notices contained
                  within such NOTICE file, excluding those notices that do not
                  pertain to any part of the Derivative Works, in at least one
                  of the following places: within a NOTICE text file distributed
                  as part of the Derivative Works; within the Source form or
                  documentation, if provided along with the Derivative Works; or,
                  within a display generated by the Derivative Works, if and
                  wherever such third-party notices normally appear. The contents
                  of the NOTICE file are for informational purposes only and
                  do not modify the License. You may add Your own attribution
                  notices within Derivative Works that You distribute, alongside
                  or as an addendum to the NOTICE text from the Work, provided
                  that such additional attribution notices cannot be construed
                  as modifying the License.
        
              You may add Your own copyright statement to Your modifications and
              may provide additional or different license terms and conditions
              for use, reproduction, or distribution of Your modifications, or
              for any such Derivative Works as a whole, provided Your use,
              reproduction, and distribution of the Work otherwise complies with
              the conditions stated in this License.
        
           5. Submission of Contributions. Unless You explicitly state otherwise,
              any Contribution intentionally submitted for inclusion in the Work
              by You to the Licensor shall be under the terms and conditions of
              this License, without any additional terms or conditions.
              Notwithstanding the above, nothing herein shall supersede or modify
              the terms of any separate license agreement you may have executed
              with Licensor regarding such Contributions.
        
           6. Trademarks. This License does not grant permission to use the trade
              names, trademarks, service marks, or product names of the Licensor,
              except as required for describing the origin of the Work and
              reproducing the content of the NOTICE file.
        
           7. Disclaimer of Warranty. Unless required by applicable law or
              agreed to in writing, Licensor provides the Work (and each
              Contributor provides its Contributions) on an "AS IS" BASIS,
              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
              implied, including, without limitation, any warranties or conditions
              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
              PARTICULAR PURPOSE. You are solely responsible for determining the
              appropriateness of using or redistributing the Work and assume any
              risks associated with Your exercise of permissions under this License.
        
           8. Limitation of Liability. In no event and under no legal theory,
              whether in tort (including negligence), contract, or otherwise,
              unless required by applicable law (such as deliberate and grossly
              negligent acts) or agreed to in writing, shall any Contributor be
              liable to You for damages, including any direct, indirect, special,
              incidental, or consequential damages of any character arising as a
              result of this License or out of the use or inability to use the
              Work (including but not limited to damages for loss of goodwill,
              work stoppage, computer failure or malfunction, or any and all
              other commercial damages or losses), even if such Contributor
              has been advised of the possibility of such damages.
        
           9. Accepting Warranty or Support. While redistributing
              the Work or Derivative Works thereof, You may choose to offer,
              and charge a fee for, acceptance of support, warranty, indemnity,
              or other liability obligations and/or rights consistent with this
              License. However, in accepting such obligations, You may act only
              on Your own behalf and on Your sole responsibility, not on behalf
              of any other Contributor, and only if You agree to indemnify,
              defend, and hold each Contributor harmless for any liability
              incurred by, or claims asserted against, such Contributor by reason
              of your accepting any such warranty or support.
        
           END OF TERMS AND CONDITIONS
        
           APPENDIX: How to apply the Apache License to your work.
        
              To apply the Apache License to your work, attach the following
              boilerplate notice, with the fields enclosed by brackets "[]"
              replaced with your own identifying information. (Don't include
              the brackets!)  The text should be enclosed in the appropriate
              comment syntax for the file format. We also recommend that a
              file or class name and description of purpose be included on the
              same "printed page" as the copyright notice for easier
              identification within third-party archives.
        
           Copyright 2026 Nick Chen
        
           Licensed under the Apache License, Version 2.0 (the "License");
           you may not use this file except in compliance with the License.
           You may obtain a copy of the License at
        
               http://www.apache.org/licenses/LICENSE-2.0
        
           Unless required by applicable law or agreed to in writing, software
           distributed under the License is distributed on an "AS IS" BASIS,
           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
           See the License for the specific language governing permissions and
           limitations under the License.
License-File: LICENSE
Keywords: agents,ai,context,cross-tool,llm,memory
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: anthropic<1,>=0.42.0
Requires-Dist: click<9,>=8.1
Requires-Dist: fastapi<0.120,>=0.115
Requires-Dist: google-generativeai<1,>=0.8.3
Requires-Dist: httpx<0.30,>=0.27
Requires-Dist: mcp<2,>=1.10
Requires-Dist: openai<3,>=1.58.0
Requires-Dist: python-frontmatter<2,>=1.1
Requires-Dist: rank-bm25<0.3,>=0.2.2
Requires-Dist: sqlite-vec<0.2,>=0.1.6
Requires-Dist: uvicorn[standard]<0.40,>=0.30
Provides-Extra: dev
Requires-Dist: build<2,>=1; extra == 'dev'
Requires-Dist: mypy<2,>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio<0.30,>=0.24; extra == 'dev'
Requires-Dist: pytest-cov<7,>=5; extra == 'dev'
Requires-Dist: pytest<9,>=8; extra == 'dev'
Requires-Dist: ruff<0.13,>=0.7; extra == 'dev'
Requires-Dist: twine<7,>=5; extra == 'dev'
Description-Content-Type: text/markdown

<div id="top">

<!-- HEADER STYLE: MODERN -->
<div align="left" style="position: relative; width: 100%; height: 100%; ">

# MNEVA

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

<!-- BADGES -->
<!-- local repository, no metadata badges. -->

<em>Built with the tools and technologies:</em>

<img src="https://img.shields.io/badge/Anthropic-191919.svg?style=flat-square&logo=Anthropic&logoColor=white" alt="Anthropic">
<img src="https://img.shields.io/badge/TOML-9C4121.svg?style=flat-square&logo=TOML&logoColor=white" alt="TOML">
<img src="https://img.shields.io/badge/Ruff-D7FF64.svg?style=flat-square&logo=Ruff&logoColor=black" alt="Ruff">
<img src="https://img.shields.io/badge/FastAPI-009688.svg?style=flat-square&logo=FastAPI&logoColor=white" alt="FastAPI">
<img src="https://img.shields.io/badge/Pytest-0A9EDC.svg?style=flat-square&logo=Pytest&logoColor=white" alt="Pytest">
<br>
<img src="https://img.shields.io/badge/Python-3776AB.svg?style=flat-square&logo=Python&logoColor=white" alt="Python">
<img src="https://img.shields.io/badge/GitHub%20Actions-2088FF.svg?style=flat-square&logo=GitHub-Actions&logoColor=white" alt="GitHub%20Actions">
<img src="https://img.shields.io/badge/OpenAI-412991.svg?style=flat-square&logo=OpenAI&logoColor=white" alt="OpenAI">
<img src="https://img.shields.io/badge/Google%20Gemini-8E75B2.svg?style=flat-square&logo=Google-Gemini&logoColor=white" alt="Google%20Gemini">

</div>
</div>
<br clear="right">

---

## Table of Contents

- [Table of Contents](#table-of-contents)
- [Overview](#overview)
- [Features](#features)
- [Project Structure](#project-structure)
    - [Project Index](#project-index)
- [Getting Started](#getting-started)
    - [Prerequisites](#prerequisites)
    - [Installation](#installation)
    - [Usage](#usage)
    - [Testing](#testing)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgments](#acknowledgments)

---

## Overview

mneva is the local-first memory layer that follows you across AI assistants. Capture a decision in Claude Desktop; ask Cursor about it tomorrow. The records live as plain Markdown under `~/.mneva/`. You own the data; mneva owns the cross-tool persistence.

**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.

**Why mneva?**

- **🔌 MCP-native memory layer:** one server, every MCP-capable AI client. `capture_memory` / `search_memory` / `forget_memory` / `list_recent_memories` / `replay_context` / `get_status` tools auto-discovered by your AI client.
- **🏠 Local-first, plain Markdown:** records live as `.md` files under `~/.mneva/`. Open them in any editor, sync via your own Obsidian vault, version with git. mneva makes zero outbound network calls unless you opt into BYOK LLM features.
- **🔍 Hybrid search:** BM25 keyword ranking with optional `sqlite-vec` vector reranking, filtered by scope and lifespan.
- **🧩 Optional BYOK intelligence:** for `synthesize` / `digest` / `distill`, bring your own Anthropic / OpenAI / Google / OpenRouter key. These are advanced power-user features, not the headline.
- **🔒 No telemetry:** mneva collects nothing. The opt-in `mneva diagnose --share` command prints a sanitized report you can copy and paste in a bug report — zero record content, stdout only.

---

## Features

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

---

## Project Structure

```sh
└── 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

<details open>
	<summary><b><code>mneva/</code></b></summary>
	<!-- __root__ Submodule -->
	<details>
		<summary><b>__root__</b></summary>
		<blockquote>
			<div class='directory-path' style='padding: 8px 0; color: #666;'>
				<code><b>⦿ __root__</b></code>
			<table style='width: 100%; border-collapse: collapse;'>
			<thead>
				<tr style='background-color: #f8f9fa;'>
					<th style='width: 30%; text-align: left; padding: 8px;'>File Name</th>
					<th style='text-align: left; padding: 8px;'>Summary</th>
				</tr>
			</thead>
				<tr style='border-bottom: 1px solid #eee;'>
					<td style='padding: 8px;'><b><a href='https://github.com/mneva-ai/mneva/blob/main/LICENSE'>LICENSE</a></b></td>
					<td style='padding: 8px;'>- 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<br>- This permissive license fosters open collaboration and community adoption while protecting both the copyright holder and users from liability<br>- It is the foundational governance for all project code.</td>
				</tr>
				<tr style='border-bottom: 1px solid #eee;'>
					<td style='padding: 8px;'><b><a href='https://github.com/mneva-ai/mneva/blob/main/mypy.ini'>mypy.ini</a></b></td>
					<td style='padding: 8px;'>- 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<br>- Maintains code quality and reduces runtime errors across the architecture.</td>
				</tr>
				<tr style='border-bottom: 1px solid #eee;'>
					<td style='padding: 8px;'><b><a href='https://github.com/mneva-ai/mneva/blob/main/pyproject.toml'>pyproject.toml</a></b></td>
					<td style='padding: 8px;'>- Configures the Mneva project as a Python package for a persistent agent context substrate and local-first CLI<br>- It declares dependencies for the server, CLI, LLM integrations, and search components<br>- It also sets up the CLI entry point and development tooling, ensuring proper packaging and distribution of the application.</td>
				</tr>
				<tr style='border-bottom: 1px solid #eee;'>
					<td style='padding: 8px;'><b><a href='https://github.com/mneva-ai/mneva/blob/main/pytest.ini'>pytest.ini</a></b></td>
					<td style='padding: 8px;'>- Configures pytest’s test discovery in the <code>tests</code> directory, adds command-line flags for concise reporting, defines an <code>integration</code> marker for filesystem and HTTP end-to-end tests, and enables asyncio mode<br>- This standardizes how the project runs its unit and integration tests, ensuring consistent behavior across the codebase.</td>
				</tr>
			</table>
		</blockquote>
	</details>
	<!-- .github Submodule -->
	<details>
		<summary><b>.github</b></summary>
		<blockquote>
			<div class='directory-path' style='padding: 8px 0; color: #666;'>
				<code><b>⦿ .github</b></code>
			<!-- workflows Submodule -->
			<details>
				<summary><b>workflows</b></summary>
				<blockquote>
					<div class='directory-path' style='padding: 8px 0; color: #666;'>
						<code><b>⦿ .github.workflows</b></code>
					<table style='width: 100%; border-collapse: collapse;'>
					<thead>
						<tr style='background-color: #f8f9fa;'>
							<th style='width: 30%; text-align: left; padding: 8px;'>File Name</th>
							<th style='text-align: left; padding: 8px;'>Summary</th>
						</tr>
					</thead>
						<tr style='border-bottom: 1px solid #eee;'>
							<td style='padding: 8px;'><b><a href='https://github.com/mneva-ai/mneva/blob/main/.github/workflows/ci.yml'>ci.yml</a></b></td>
							<td style='padding: 8px;'>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.</td>
						</tr>
						<tr style='border-bottom: 1px solid #eee;'>
							<td style='padding: 8px;'><b><a href='https://github.com/mneva-ai/mneva/blob/main/.github/workflows/install-verify.yml'>install-verify.yml</a></b></td>
							<td style='padding: 8px;'>- 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<br>- This ensures the released package is functional and accessible, integral to the projects continuous integration and delivery pipeline.</td>
						</tr>
					</table>
				</blockquote>
			</details>
		</blockquote>
	</details>
	<!-- src Submodule -->
	<details>
		<summary><b>src</b></summary>
		<blockquote>
			<div class='directory-path' style='padding: 8px 0; color: #666;'>
				<code><b>⦿ src</b></code>
			<!-- mneva Submodule -->
			<details>
				<summary><b>mneva</b></summary>
				<blockquote>
					<div class='directory-path' style='padding: 8px 0; color: #666;'>
						<code><b>⦿ src.mneva</b></code>
					<table style='width: 100%; border-collapse: collapse;'>
					<thead>
						<tr style='background-color: #f8f9fa;'>
							<th style='width: 30%; text-align: left; padding: 8px;'>File Name</th>
							<th style='text-align: left; padding: 8px;'>Summary</th>
						</tr>
					</thead>
						<tr style='border-bottom: 1px solid #eee;'>
							<td style='padding: 8px;'><b><a href='https://github.com/mneva-ai/mneva/blob/main/src/mneva/api.py'>api.py</a></b></td>
							<td style='padding: 8px;'>- Defines the FastAPI web application exposing endpoints for capturing, forgetting, searching, and replaying records<br>- Integrates authentication via token middleware, coordinates with the indexer for search, store for persistence, and replay module for output<br>- Provides the primary HTTP interface through which external tools interact with the Mneva knowledge base.</td>
						</tr>
						<tr style='border-bottom: 1px solid #eee;'>
							<td style='padding: 8px;'><b><a href='https://github.com/mneva-ai/mneva/blob/main/src/mneva/cli.py'>cli.py</a></b></td>
							<td style='padding: 8px;'>- Defines the command-line interface for the mneva persistent agent context substrate using Click<br>- 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<br>- This module acts as the primary user-facing entry point.</td>
						</tr>
						<tr style='border-bottom: 1px solid #eee;'>
							<td style='padding: 8px;'><b><a href='https://github.com/mneva-ai/mneva/blob/main/src/mneva/config.py'>config.py</a></b></td>
							<td style='padding: 8px;'>- 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<br>- This centralizes configuration handling, ensuring consistent access to runtime parameters across the entire codebase.</td>
						</tr>
						<tr style='border-bottom: 1px solid #eee;'>
							<td style='padding: 8px;'><b><a href='https://github.com/mneva-ai/mneva/blob/main/src/mneva/indexer.py'>indexer.py</a></b></td>
							<td style='padding: 8px;'>- Implements a hybrid search index that combines BM25 ranking with optional sqlite-vec re-ranking for querying stored records<br>- Manages record insertion, deletion, and retrieval with filtering by scope and lifespan<br>- Supports both full-text and vector-powered search modes, returning the top-k relevant records for a given query.</td>
						</tr>
						<tr style='border-bottom: 1px solid #eee;'>
							<td style='padding: 8px;'><b><a href='https://github.com/mneva-ai/mneva/blob/main/src/mneva/paths.py'>paths.py</a></b></td>
							<td style='padding: 8px;'>- Manages the applications home directory by respecting the $MNEVA_HOME environment variable or defaulting to ~/.mneva<br>- Ensures the root and required subdirectories (store, index, adr, templates) exist, creating them idempotently<br>- This foundational module enables consistent data storage and retrieval across the entire codebase.</td>
						</tr>
						<tr style='border-bottom: 1px solid #eee;'>
							<td style='padding: 8px;'><b><a href='https://github.com/mneva-ai/mneva/blob/main/src/mneva/replay.py'>replay.py</a></b></td>
							<td style='padding: 8px;'>- Generates context replay blocks for supported tools by combining template bodies with captured permanent records, optionally filtered by scope<br>- Serves as shared logic used by both the mneva replay CLI command and the GET /replay HTTP endpoint, ensuring consistent output formatting across interfaces.</td>
						</tr>
						<tr style='border-bottom: 1px solid #eee;'>
							<td style='padding: 8px;'><b><a href='https://github.com/mneva-ai/mneva/blob/main/src/mneva/store.py'>store.py</a></b></td>
							<td style='padding: 8px;'>- Persists and retrieves structured records as markdown files with frontmatter metadata, serving as the data access layer for the projects file-based store<br>- It handles serialization and provides create, read, update, delete, and iteration operations, abstracting file system details from the rest of the codebase.</td>
						</tr>
						<tr style='border-bottom: 1px solid #eee;'>
							<td style='padding: 8px;'><b><a href='https://github.com/mneva-ai/mneva/blob/main/src/mneva/synth.py'>synth.py</a></b></td>
							<td style='padding: 8px;'>- Implements a two-stage brainstorming and critical analysis pipeline using captured context records, along with a digest generator for producing L1 bootstrap summaries<br>- 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.</td>
						</tr>
					</table>
					<!-- providers Submodule -->
					<details>
						<summary><b>providers</b></summary>
						<blockquote>
							<div class='directory-path' style='padding: 8px 0; color: #666;'>
								<code><b>⦿ src.mneva.providers</b></code>
							<table style='width: 100%; border-collapse: collapse;'>
							<thead>
								<tr style='background-color: #f8f9fa;'>
									<th style='width: 30%; text-align: left; padding: 8px;'>File Name</th>
									<th style='text-align: left; padding: 8px;'>Summary</th>
								</tr>
							</thead>
								<tr style='border-bottom: 1px solid #eee;'>
									<td style='padding: 8px;'><b><a href='https://github.com/mneva-ai/mneva/blob/main/src\mneva/providers/anthropic.py'>anthropic.py</a></b></td>
									<td style='padding: 8px;'>- Enables prompt-driven text completions through Anthropics API, using a default large-context model<br>- Handles authentication by checking for an API key in environment variables and raises an error if missing<br>- This provider supports the systems extensible architecture by abstracting Anthropic as one of multiple possible AI backends.</td>
								</tr>
								<tr style='border-bottom: 1px solid #eee;'>
									<td style='padding: 8px;'><b><a href='https://github.com/mneva-ai/mneva/blob/main/src\mneva/providers/base.py'>base.py</a></b></td>
									<td style='padding: 8px;'>- Defines the Provider protocol and error classes that form the foundation for all LLM adapter implementations<br>- Providers implement a one-shot non-streaming complete method, relying solely on environment variables for API keys<br>- MissingAPIKeyError enforces secure key management, while ProviderError serves as a catch-all for provider-side failures.</td>
								</tr>
								<tr style='border-bottom: 1px solid #eee;'>
									<td style='padding: 8px;'><b><a href='https://github.com/mneva-ai/mneva/blob/main/src\mneva/providers/google.py'>google.py</a></b></td>
									<td style='padding: 8px;'>- 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<br>- 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.</td>
								</tr>
								<tr style='border-bottom: 1px solid #eee;'>
									<td style='padding: 8px;'><b><a href='https://github.com/mneva-ai/mneva/blob/main/src\mneva/providers/openai.py'>openai.py</a></b></td>
									<td style='padding: 8px;'>- Provides integration with OpenAIs GPT-5 model as the default provider for completions<br>- Handles API key authentication from environment variables and offers a simple interface to generate text responses<br>- This enables the mneva system to leverage OpenAIs large language models for various tasks.</td>
								</tr>
								<tr style='border-bottom: 1px solid #eee;'>
									<td style='padding: 8px;'><b><a href='https://github.com/mneva-ai/mneva/blob/main/src\mneva/providers/openrouter.py'>openrouter.py</a></b></td>
									<td style='padding: 8px;'>- 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<br>- The model is configurable via environment variable, and it validates the API key at initialization, raising a helpful error if missing<br>- Its role in the provider pattern ensures a consistent interface for completion tasks across different backends.</td>
								</tr>
							</table>
						</blockquote>
					</details>
				</blockquote>
			</details>
		</blockquote>
	</details>
</details>

---

## 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)

Pick the AI client 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.

**Claude Desktop** — edit `claude_desktop_config.json`:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

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

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

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

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

```json
{
  "mcpServers": {
    "mneva": {
      "command": "uvx",
      "args": ["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.

```sh
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
```

### 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. Until v0.3 ships a browser extension, the workaround is:

| Your AI                                | v0.2 native support              | Workaround                                              |
| -------------------------------------- | -------------------------------- | ------------------------------------------------------- |
| Claude Desktop / Claude Code           | ✅ MCP                            | —                                                       |
| Cursor / Windsurf / Cline / Continue   | ✅ MCP                            | —                                                       |
| ChatGPT Desktop                        | ⚠️ MCP (Developer Mode beta)     | Enable Developer Mode in the app                        |
| claude.ai web                          | ❌                                | Install Claude Desktop (same account, same memory)      |
| chatgpt.com web                        | ❌                                | Install ChatGPT Desktop + Developer Mode                |
| gemini.google.com                      | ❌                                | CLI manual workflow (below)                             |
| DeepSeek web                           | ❌                                | CLI manual workflow (below)                             |

**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.

### 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]"`.

### 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`](./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:

```sh
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`](./.github/workflows/ci.yml).

---

## Roadmap

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

- [X] **v0.1.0** — CLI + store + BM25/sqlite-vec index + replay templates + HTTP API + four-provider BYOK
- [X] **v0.1.x** — Gap fixes, Obsidian vault read-write integration, `mneva distill`, CI matrix forward-defense
- [X] **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** — 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](https://github.com/mneva-ai/mneva/discussions)**: Share your insights, provide feedback, or ask questions.
- **🐛 [Report Issues](https://github.com/mneva-ai/mneva/issues)**: Submit bugs found or log feature requests for the `mneva` project.
- **💡 [Submit Pull Requests](https://github.com/mneva-ai/mneva/blob/main/CONTRIBUTING.md)**: Review open PRs, and submit your own PRs.

<details closed>
<summary>Contributing Guidelines</summary>

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.
   ```sh
   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.
   ```sh
   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.
   ```sh
   git commit -m 'Implemented new feature x.'
   ```
6. **Push to GitHub**: Push the changes to your forked repository.
   ```sh
   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!
</details>

<details closed>
<summary>Contributor Graph</summary>
<br>
<p align="left">
   <a href="https://github.com/mneva-ai/mneva/graphs/contributors">
      <img src="https://contrib.rocks/image?repo=mneva-ai/mneva">
   </a>
</p>
</details>

---

## License

Mneva is licensed under the [Apache License 2.0](./LICENSE).

---

## 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`](./CHANGELOG.md)

<div align="right">

[![][back-to-top]](#top)

</div>


[back-to-top]: https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square


---
