mnemon-memory 0.2.0__tar.gz

mnemon_memory-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v
+
+  secrets:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

mnemon_memory-0.2.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+
+# Vault data (local only)
+*.sqlite
+*.sqlite-wal
+*.sqlite-shm
+*.vec
+*.vec.npz
+
+# GGUF models
+*.gguf
+
+# Environment / secrets
+.env
+.env.*
+
+# Editors / OS
+.idea/
+.vscode/
+.cursor/
+.DS_Store
+
+# Logs / caches
+*.log
+.cache/
+.coverage
+
+# Legacy TypeScript
+ts/
+node_modules/
+
+# Flow Doctor (testing artifact)
+flow_doctor.db

mnemon_memory-0.2.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## [0.2.0] - 2026-04-09
+
+### Added
+- Full Python rewrite (was TypeScript/Bun in v0.1.x)
+- 13 MCP tools: search, get, timeline, save, pin, forget, status, sweep, related, rebuild, check_contradictions, profile_get, profile_update
+- Hybrid BM25 + vector search with Reciprocal Rank Fusion and MMR diversity filtering
+- Composite scoring: 0.5 * relevance + 0.25 * recency + 0.25 * confidence
+- FastEmbed embeddings (bge-small-en-v1.5, 384d ONNX — no PyTorch needed)
+- Memory lifecycle: content-type-based half-life decay, pinning, archival via sweep
+- Contradiction detection with confidence decay (vector similarity + optional LLM classification)
+- Claude Code hooks: context surfacing (UserPromptSubmit), session extraction (Stop), handoff generation (Stop)
+- Auto-configure command: `mnemon setup claude-code|cursor|gemini|hooks`
+- Remote Streamable HTTP server via FastMCP native transport
+- S3 vault sync (push/pull via AWS CLI)
+- CLI: serve, serve-remote, status, search, save, forget, sync, setup
+- Optional local LLM (QMD-1.7B via llama-cpp-python) for query expansion, extraction, contradiction detection
+- 253 tests, 90% coverage
+
+### Changed
+- Rewritten from TypeScript (Bun) to Python (>=3.10)
+- Storage: SQLite + FTS5 + numpy vector store (was SQLite + FTS5 + TypeScript vector store)
+- Embedding: FastEmbed bge-small-en-v1.5 (was EmbeddingGemma-300M)
+- Build: hatchling (was Bun bundler)
+- Package distribution: PyPI (was npm)
+
+## [0.1.x] - 2026-04-08
+
+Initial TypeScript implementation (deprecated, replaced by Python rewrite in v0.2.0).

mnemon_memory-0.2.0/CLAUDE.md

@@ -0,0 +1,65 @@
+# mnemon
+
+Universal long-term memory layer for AI agents via MCP.
+
+## Stack
+
+- **Runtime:** Python >= 3.10
+- **Storage:** SQLite + FTS5 + in-process vector store (single-file vault at `~/.mnemon/default.sqlite`)
+- **Embedding:** FastEmbed with bge-small-en-v1.5 (384d, ONNX, ~13MB)
+- **LLM (optional):** QMD-query-expansion-1.7B (GGUF via llama-cpp-python, for extraction + expansion)
+- **MCP:** FastMCP (stdio + Streamable HTTP transports)
+- **Package:** hatchling build backend, `pip install -e ".[dev]"` for development
+
+## Key files
+
+```
+src/mnemon/
+  store.py              # SQLite storage — content, documents, FTS5, relations
+  vecstore.py           # In-process vector store — brute-force cosine over numpy arrays
+  embedder.py           # FastEmbed bge-small-en-v1.5 wrapper
+  search.py             # BM25 + vector + query expansion + RRF fusion + MMR
+  llm.py                # QMD-1.7B via llama-cpp-python (optional)
+  contradiction.py      # Contradiction detection + confidence decay
+  config.py             # Content types, half-lives, scoring constants
+  server.py             # MCP server (stdio) — 13 tools
+  server_remote.py      # Remote HTTP server (Streamable HTTP)
+  sync.py               # S3 vault sync (push/pull via AWS CLI)
+  setup.py              # Auto-configure Claude Code, Cursor, Gemini
+  cli.py                # CLI dispatcher
+  __init__.py           # Version
+  hooks/
+    framework.py        # Hook framework — stdin/stdout, dedup, noise filtering
+    context_surfacing.py  # UserPromptSubmit — search + inject context
+    session_extractor.py  # Stop — extract observations (LLM or regex)
+    handoff_generator.py  # Stop — session summary (LLM or template)
+```
+
+## Commands
+
+```bash
+# Development
+pip install -e ".[dev]"         # Install with dev deps
+pytest                          # Run tests (102 tests)
+pytest -v                       # Verbose output
+pytest tests/test_store.py      # Single file
+
+# CLI
+mnemon serve                    # MCP server (stdio)
+mnemon serve-remote             # HTTP server (Streamable HTTP)
+mnemon status                   # Vault health
+mnemon search <query>           # Search memories
+mnemon save <title> <content>   # Save a memory
+mnemon setup <target>           # Configure (claude-code, cursor, gemini, hooks)
+mnemon sync <push|pull>         # S3 vault sync
+```
+
+## Testing
+
+All tests must pass before committing. Tests use temporary SQLite databases and mock external dependencies (LLM, embeddings, AWS CLI).
+
+```bash
+pytest                          # Quick check
+pytest -v                       # See individual test names
+pytest --tb=short               # Shorter tracebacks on failure
+```

mnemon_memory-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian McMahon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mnemon_memory-0.2.0/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.4
+Name: mnemon-memory
+Version: 0.2.0
+Summary: Universal long-term memory layer for AI agents via MCP
+Project-URL: Homepage, https://github.com/cipher813/mnemon
+Project-URL: Repository, https://github.com/cipher813/mnemon
+Project-URL: Issues, https://github.com/cipher813/mnemon/issues
+Project-URL: Changelog, https://github.com/cipher813/mnemon/blob/main/CHANGELOG.md
+Author-email: Brian McMahon <cipher813@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,llm,mcp,memory,sqlite,vector-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: fastembed>=0.3
+Requires-Dist: mcp>=1.27
+Requires-Dist: numpy>=1.24
+Provides-Extra: all
+Requires-Dist: httpx>=0.27; extra == 'all'
+Requires-Dist: huggingface-hub>=0.20; extra == 'all'
+Requires-Dist: llama-cpp-python>=0.3; extra == 'all'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'all'
+Requires-Dist: pytest-cov>=5.0; extra == 'all'
+Requires-Dist: pytest>=8.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: huggingface-hub>=0.20; extra == 'llm'
+Requires-Dist: llama-cpp-python>=0.3; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# mnemon
+
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)]()
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-253_passing-brightgreen.svg)]()
+[![Coverage](https://img.shields.io/badge/coverage-90%25-brightgreen.svg)]()
+[![MCP](https://img.shields.io/badge/MCP-compatible-blueviolet.svg)](https://modelcontextprotocol.io)
+[![PyPI](https://img.shields.io/badge/PyPI-v0.2.0-blue.svg)](https://pypi.org/project/mnemon-memory/)
+
+> Universal long-term memory layer for AI agents via [MCP](https://modelcontextprotocol.io).
+
+mnemon gives AI agents persistent, searchable memory that survives across sessions. It stores memories in a local SQLite vault with hybrid BM25 + vector search, automatic confidence decay, contradiction detection, and the Model Context Protocol for seamless integration with Claude Code, Cursor, and other MCP clients.
+
+## Table of Contents
+
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [MCP Tools](#mcp-tools)
+- [Memory Types](#memory-types)
+- [Claude Code Hooks](#claude-code-hooks)
+- [Remote Server](#remote-server)
+- [S3 Vault Sync](#s3-vault-sync)
+- [Architecture](#architecture)
+- [Configuration](#configuration)
+- [Development](#development)
+
+---
+
+## Install
+
+```bash
+pip install mnemon-memory
+```
+
+With optional LLM support (local 1.7B model for query expansion, contradiction detection, and smarter session extraction):
+
+```bash
+pip install "mnemon-memory[llm]"
+```
+
+From source:
+
+```bash
+git clone https://github.com/cipher813/mnemon.git
+cd mnemon
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### 1. Configure your client
+
+```bash
+# Auto-configure Claude Code (MCP server + memory hooks)
+mnemon setup claude-code
+
+# Or configure Cursor
+mnemon setup cursor
+
+# Or just the hooks (if MCP is already configured)
+mnemon setup hooks
+```
+
+### 2. Use it
+
+Once configured, mnemon works automatically:
+
+- **Context surfacing**: relevant memories are injected before each prompt
+- **Session extraction**: decisions, preferences, and observations are saved at session end
+- **Handoff generation**: session summaries maintain continuity across sessions
+
+You can also interact with memories directly via MCP tools or CLI:
+
+```bash
+mnemon search "deployment architecture"
+mnemon save "DB migration plan" "Migrate from PostgreSQL to DynamoDB in Q3"
+mnemon forget 42
+mnemon status
+```
+
+## MCP Tools
+
+### Retrieval
+
+| Tool | Description |
+|------|-------------|
+| `memory_search` | Hybrid BM25 + vector search with composite scoring (relevance + recency + confidence) |
+| `memory_get` | Fetch a specific memory by ID with full content |
+| `memory_timeline` | Recent memories in reverse chronological order |
+| `memory_related` | Find memories related to a given memory via the relationship graph |
+
+### Mutation
+
+| Tool | Description |
+|------|-------------|
+| `memory_save` | Store a new memory with content type classification and auto-embedding |
+| `memory_pin` | Pin a memory to boost confidence and prevent archival |
+| `memory_forget` | Soft-delete a memory (marked as invalidated, not physically removed) |
+
+### Lifecycle
+
+| Tool | Description |
+|------|-------------|
+| `memory_status` | Vault health stats — counts by type, vectors, pinned/invalidated |
+| `memory_sweep` | Archive stale memories past their half-life (dry-run by default) |
+| `memory_rebuild` | Re-embed all documents (use after upgrading embedding model) |
+
+### Intelligence
+
+| Tool | Description |
+|------|-------------|
+| `memory_check_contradictions` | Check a memory for conflicts using vector similarity + LLM classification |
+| `profile_get` | Synthesized user profile from stored preferences and decisions |
+| `profile_update` | Manually add a fact to the user profile |
+
+## Memory Types
+
+Each memory has a content type that determines its default confidence and decay half-life:
+
+| Type | Default Confidence | Half-Life | Use for |
+|------|-------------------|-----------|---------|
+| `decision` | 0.85 | Never | Architectural choices, design decisions |
+| `preference` | 0.80 | Never | User workflow habits, style preferences |
+| `antipattern` | 0.80 | Never | Things that failed, approaches to avoid |
+| `observation` | 0.70 | 90 days | Learned facts, discovered behaviors |
+| `research` | 0.70 | 90 days | Investigation results, findings |
+| `project` | 0.65 | 120 days | Project status, goals, context |
+| `handoff` | 0.60 | 30 days | Session summaries for continuity |
+| `note` | 0.50 | 60 days | General notes, default type |
+
+Memories with access activity decay slower — each access extends the effective half-life by 10%, up to 3x the base value.
+
+## Claude Code Hooks
+
+When configured via `mnemon setup claude-code`, three hooks are installed:
+
+| Hook | Event | Timeout | Description |
+|------|-------|---------|-------------|
+| Context surfacing | `UserPromptSubmit` | 8s | Searches vault and injects relevant memories as context |
+| Session extractor | `Stop` | 30s | Extracts decisions, preferences, and observations from the transcript |
+| Handoff generator | `Stop` | 30s | Creates a session summary for the next session |
+
+The extractor and handoff generator use LLM-based extraction when `mnemon[llm]` is installed, with regex/heuristic fallback otherwise.
+
+## Remote Server
+
+For use with Claude.ai web or iOS (any Streamable HTTP MCP client):
+
+```bash
+# Start remote server
+mnemon serve-remote
+
+# With authentication (at proxy/infra level)
+MNEMON_TOKEN=your-secret-token mnemon serve-remote
+
+# Custom port
+PORT=9000 mnemon serve-remote
+```
+
+The remote server exposes the same MCP tools as stdio mode via FastMCP's native Streamable HTTP transport at `http://localhost:8502/mcp`.
+
+## S3 Vault Sync
+
+Sync your vault across machines via S3:
+
+```bash
+# Push local vault to S3
+MNEMON_S3_BUCKET=my-bucket mnemon sync push
+
+# Pull vault from S3
+MNEMON_S3_BUCKET=my-bucket mnemon sync pull
+```
+
+| Env var | Default | Description |
+|---------|---------|-------------|
+| `MNEMON_S3_BUCKET` | (required) | S3 bucket name |
+| `MNEMON_S3_PREFIX` | `mnemon/vaults` | S3 key prefix |
+| `MNEMON_VAULT_NAME` | `default` | Vault name |
+
+Requires the AWS CLI (`aws`) on your PATH with valid credentials.
+
+## Architecture
+
+```
+~/.mnemon/
+  default.sqlite      SQLite vault (FTS5 + WAL mode)
+  default.vec.npz     Companion vector store (numpy, brute-force cosine)
+```
+
+- **Storage**: SQLite with FTS5 full-text search, content-addressable deduplication (SHA-256)
+- **Search**: Hybrid BM25 + vector (384d, bge-small-en-v1.5 via FastEmbed) fused with Reciprocal Rank Fusion
+- **Scoring**: Composite score = 0.5 * relevance + 0.25 * recency + 0.25 * confidence
+- **Diversity**: MMR filtering (Jaccard bigram similarity > 0.6 demoted by 50%)
+- **Intelligence** (optional): Local 1.7B LLM (QMD-query-expansion) for query expansion, contradiction detection, session extraction — zero API cost
+- **Transport**: MCP stdio (local) and Streamable HTTP (remote)
+
+## Configuration
+
+| Env var | Default | Description |
+|---------|---------|-------------|
+| `MNEMON_VAULT_DIR` | `~/.mnemon` | Vault directory |
+| `MNEMON_TOKEN` | (none) | Bearer token for remote server auth |
+| `MNEMON_MODEL_DIR` | `~/.mnemon/models` | Directory for LLM model files |
+| `PORT` | `8502` | Remote server port |
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests (253 tests)
+pytest
+
+# Run tests with coverage
+pytest --cov=mnemon --cov-report=term-missing
+
+# Run a specific test file
+pytest tests/test_store.py -v
+```
+
+## License
+
+MIT

mnemon_memory-0.2.0/README.md

@@ -0,0 +1,224 @@
+# mnemon
+
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)]()
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-253_passing-brightgreen.svg)]()
+[![Coverage](https://img.shields.io/badge/coverage-90%25-brightgreen.svg)]()
+[![MCP](https://img.shields.io/badge/MCP-compatible-blueviolet.svg)](https://modelcontextprotocol.io)
+[![PyPI](https://img.shields.io/badge/PyPI-v0.2.0-blue.svg)](https://pypi.org/project/mnemon-memory/)
+
+> Universal long-term memory layer for AI agents via [MCP](https://modelcontextprotocol.io).
+
+mnemon gives AI agents persistent, searchable memory that survives across sessions. It stores memories in a local SQLite vault with hybrid BM25 + vector search, automatic confidence decay, contradiction detection, and the Model Context Protocol for seamless integration with Claude Code, Cursor, and other MCP clients.
+
+## Table of Contents
+
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [MCP Tools](#mcp-tools)
+- [Memory Types](#memory-types)
+- [Claude Code Hooks](#claude-code-hooks)
+- [Remote Server](#remote-server)
+- [S3 Vault Sync](#s3-vault-sync)
+- [Architecture](#architecture)
+- [Configuration](#configuration)
+- [Development](#development)
+
+---
+
+## Install
+
+```bash
+pip install mnemon-memory
+```
+
+With optional LLM support (local 1.7B model for query expansion, contradiction detection, and smarter session extraction):
+
+```bash
+pip install "mnemon-memory[llm]"
+```
+
+From source:
+
+```bash
+git clone https://github.com/cipher813/mnemon.git
+cd mnemon
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### 1. Configure your client
+
+```bash
+# Auto-configure Claude Code (MCP server + memory hooks)
+mnemon setup claude-code
+
+# Or configure Cursor
+mnemon setup cursor
+
+# Or just the hooks (if MCP is already configured)
+mnemon setup hooks
+```
+
+### 2. Use it
+
+Once configured, mnemon works automatically:
+
+- **Context surfacing**: relevant memories are injected before each prompt
+- **Session extraction**: decisions, preferences, and observations are saved at session end
+- **Handoff generation**: session summaries maintain continuity across sessions
+
+You can also interact with memories directly via MCP tools or CLI:
+
+```bash
+mnemon search "deployment architecture"
+mnemon save "DB migration plan" "Migrate from PostgreSQL to DynamoDB in Q3"
+mnemon forget 42
+mnemon status
+```
+
+## MCP Tools
+
+### Retrieval
+
+| Tool | Description |
+|------|-------------|
+| `memory_search` | Hybrid BM25 + vector search with composite scoring (relevance + recency + confidence) |
+| `memory_get` | Fetch a specific memory by ID with full content |
+| `memory_timeline` | Recent memories in reverse chronological order |
+| `memory_related` | Find memories related to a given memory via the relationship graph |
+
+### Mutation
+
+| Tool | Description |
+|------|-------------|
+| `memory_save` | Store a new memory with content type classification and auto-embedding |
+| `memory_pin` | Pin a memory to boost confidence and prevent archival |
+| `memory_forget` | Soft-delete a memory (marked as invalidated, not physically removed) |
+
+### Lifecycle
+
+| Tool | Description |
+|------|-------------|
+| `memory_status` | Vault health stats — counts by type, vectors, pinned/invalidated |
+| `memory_sweep` | Archive stale memories past their half-life (dry-run by default) |
+| `memory_rebuild` | Re-embed all documents (use after upgrading embedding model) |
+
+### Intelligence
+
+| Tool | Description |
+|------|-------------|
+| `memory_check_contradictions` | Check a memory for conflicts using vector similarity + LLM classification |
+| `profile_get` | Synthesized user profile from stored preferences and decisions |
+| `profile_update` | Manually add a fact to the user profile |
+
+## Memory Types
+
+Each memory has a content type that determines its default confidence and decay half-life:
+
+| Type | Default Confidence | Half-Life | Use for |
+|------|-------------------|-----------|---------|
+| `decision` | 0.85 | Never | Architectural choices, design decisions |
+| `preference` | 0.80 | Never | User workflow habits, style preferences |
+| `antipattern` | 0.80 | Never | Things that failed, approaches to avoid |
+| `observation` | 0.70 | 90 days | Learned facts, discovered behaviors |
+| `research` | 0.70 | 90 days | Investigation results, findings |
+| `project` | 0.65 | 120 days | Project status, goals, context |
+| `handoff` | 0.60 | 30 days | Session summaries for continuity |
+| `note` | 0.50 | 60 days | General notes, default type |
+
+Memories with access activity decay slower — each access extends the effective half-life by 10%, up to 3x the base value.
+
+## Claude Code Hooks
+
+When configured via `mnemon setup claude-code`, three hooks are installed:
+
+| Hook | Event | Timeout | Description |
+|------|-------|---------|-------------|
+| Context surfacing | `UserPromptSubmit` | 8s | Searches vault and injects relevant memories as context |
+| Session extractor | `Stop` | 30s | Extracts decisions, preferences, and observations from the transcript |
+| Handoff generator | `Stop` | 30s | Creates a session summary for the next session |
+
+The extractor and handoff generator use LLM-based extraction when `mnemon[llm]` is installed, with regex/heuristic fallback otherwise.
+
+## Remote Server
+
+For use with Claude.ai web or iOS (any Streamable HTTP MCP client):
+
+```bash
+# Start remote server
+mnemon serve-remote
+
+# With authentication (at proxy/infra level)
+MNEMON_TOKEN=your-secret-token mnemon serve-remote
+
+# Custom port
+PORT=9000 mnemon serve-remote
+```
+
+The remote server exposes the same MCP tools as stdio mode via FastMCP's native Streamable HTTP transport at `http://localhost:8502/mcp`.
+
+## S3 Vault Sync
+
+Sync your vault across machines via S3:
+
+```bash
+# Push local vault to S3
+MNEMON_S3_BUCKET=my-bucket mnemon sync push
+
+# Pull vault from S3
+MNEMON_S3_BUCKET=my-bucket mnemon sync pull
+```
+
+| Env var | Default | Description |
+|---------|---------|-------------|
+| `MNEMON_S3_BUCKET` | (required) | S3 bucket name |
+| `MNEMON_S3_PREFIX` | `mnemon/vaults` | S3 key prefix |
+| `MNEMON_VAULT_NAME` | `default` | Vault name |
+
+Requires the AWS CLI (`aws`) on your PATH with valid credentials.
+
+## Architecture
+
+```
+~/.mnemon/
+  default.sqlite      SQLite vault (FTS5 + WAL mode)
+  default.vec.npz     Companion vector store (numpy, brute-force cosine)
+```
+
+- **Storage**: SQLite with FTS5 full-text search, content-addressable deduplication (SHA-256)
+- **Search**: Hybrid BM25 + vector (384d, bge-small-en-v1.5 via FastEmbed) fused with Reciprocal Rank Fusion
+- **Scoring**: Composite score = 0.5 * relevance + 0.25 * recency + 0.25 * confidence
+- **Diversity**: MMR filtering (Jaccard bigram similarity > 0.6 demoted by 50%)
+- **Intelligence** (optional): Local 1.7B LLM (QMD-query-expansion) for query expansion, contradiction detection, session extraction — zero API cost
+- **Transport**: MCP stdio (local) and Streamable HTTP (remote)
+
+## Configuration
+
+| Env var | Default | Description |
+|---------|---------|-------------|
+| `MNEMON_VAULT_DIR` | `~/.mnemon` | Vault directory |
+| `MNEMON_TOKEN` | (none) | Bearer token for remote server auth |
+| `MNEMON_MODEL_DIR` | `~/.mnemon/models` | Directory for LLM model files |
+| `PORT` | `8502` | Remote server port |
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests (253 tests)
+pytest
+
+# Run tests with coverage
+pytest --cov=mnemon --cov-report=term-missing
+
+# Run a specific test file
+pytest tests/test_store.py -v
+```
+
+## License
+
+MIT