memorymaster 3.5.0__tar.gz → 3.5.1__tar.gz

memorymaster-3.5.1/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: memorymaster
+Version: 3.5.1
+Summary: Production-grade memory reliability system for AI coding agents. Lifecycle-managed claims with citations, conflict detection, steward governance, and MCP integration.
+Author: wolverin0
+License: MIT
+Keywords: memory,ai-agents,claims,lifecycle,mcp,sqlite,postgres,coding-agents
+Classifier: Development Status :: 5 - Production/Stable
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.2; extra == "postgres"
+Provides-Extra: security
+Requires-Dist: cryptography>=42; extra == "security"
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers>=3.0; extra == "embeddings"
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.0; extra == "gemini"
+Provides-Extra: qdrant
+Requires-Dist: httpx>=0.27; extra == "qdrant"
+Provides-Extra: vector
+Requires-Dist: sentence-transformers>=3.0; extra == "vector"
+Requires-Dist: qdrant-client>=1.9; extra == "vector"
+Provides-Extra: graph
+Requires-Dist: kuzu>=0.4; extra == "graph"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: pytest-cov>=6.0; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+Provides-Extra: ml
+Requires-Dist: scikit-learn>=1.3; extra == "ml"
+Requires-Dist: joblib>=1.3; extra == "ml"
+Dynamic: license-file
+
+# MemoryMaster
+
+**Production-grade memory reliability system for AI coding agents.**
+
+Lifecycle-managed claims with citations, conflict detection, steward governance, hybrid retrieval, and MCP integration. Give your AI agents persistent, trustworthy memory.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Tests](https://img.shields.io/badge/tests-1029-green.svg)]()
+[![MCP Tools](https://img.shields.io/badge/MCP%20tools-22-purple.svg)]()
+[![CLI Commands](https://img.shields.io/badge/CLI%20commands-64-orange.svg)]()
+[![PyPI](https://img.shields.io/pypi/v/memorymaster.svg)](https://pypi.org/project/memorymaster/)
+
+MemoryMaster prevents the #1 problem with agent memory: **drift, stale assumptions, and unsafe disclosure**. It gives Claude Code, Codex, and any MCP-compatible agent persistent, verifiable memory with a full claim lifecycle, citation tracking, conflict detection, and human-in-the-loop governance.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Agent Runtime                            │
+│  (Claude Code / Codex / any MCP-compatible agent)               │
+└────────────┬────────────────────────────────┬───────────────────┘
+             │ MCP (22 tools)                 │ CLI (64 commands)
+             v                                v
+┌─────────────────────────────────────────────────────────────────┐
+│                      MemoryMaster Core                          │
+│  ┌──────────┐  ┌───────────┐  ┌──────────┐  ┌───────────────┐  │
+│  │ Ingestor │  │ Extractor │  │ Validator │  │ State Engine  │  │
+│  │ (events) │->│ (claims)  │->│ (probes)  │->│ (6-state FSM) │  │
+│  └──────────┘  └───────────┘  └──────────┘  └───────────────┘  │
+│  ┌──────────┐  ┌───────────┐  ┌──────────┐  ┌───────────────┐  │
+│  │ Retrieval│  │ Compactor │  │ Steward  │  │  Dashboard    │  │
+│  │ (hybrid) │  │ (archive) │  │ (govern) │  │  (HTML+SSE)   │  │
+│  └──────────┘  └───────────┘  └──────────┘  └───────────────┘  │
+└────────┬──────────────┬──────────────┬──────────┬───────────────┘
+         v              v              v          v
+   SQLite/Postgres   Qdrant      Ollama/CLI    Claude Code
+                    (vectors)   (LLM stack)   Auto Dream + Vault
+```
+
+## Key features
+
+- **6-state lifecycle**: `candidate` → `confirmed` → `stale` → `superseded` → `conflicted` → `archived`
+- **Citation tracking** with provenance for every claim
+- **Hybrid retrieval**: vector (sentence-transformers / Gemini) + FTS5 + freshness + confidence
+- **Context optimizer**: `query_for_context(budget=4000)` returns auto-curated memory that fits your token budget
+- **Entity graph** with typed relationships and alias resolution
+- **Steward governance**: multi-probe validators (filesystem, format, citation, semantic, tool) with proposal review
+- **Conflict resolution**: 5-tier auto (confidence > freshness > citations > LLM > manual)
+- **Auto-redaction** at ingest: JWT, GitHub tokens, Bearer, AWS keys, SSH keys, custom patterns
+- **LLM Wiki**: compiled-truth + append-only timeline articles with progressive-disclosure frontmatter
+- **Dual backend**: SQLite (zero-config) and Postgres (full feature parity with pgvector)
+- **Dream Bridge** for bidirectional sync with Claude Code's Auto Dream
+- **7-hook stack**: recall, classify, validate-wiki, session-start, auto-ingest, precompact, steward-cron
+
+Full feature index lives in [`docs/handbook.md`](docs/handbook.md).
+
+## Prerequisites
+
+**Required**
+
+- Python **3.10+** with `pip`
+- Claude Code, Codex, or any MCP-compatible agent
+
+**Optional**
+
+- **Already a Claude Code subscriber?** No API key needed — set `MEMORYMASTER_LLM_PROVIDER=claude_cli` and the steward + auto-ingest hooks will use your existing OAuth via the local `claude --print` binary
+- A free Gemini API key from [aistudio.google.com](https://aistudio.google.com) — powers the auto-ingest hook at ~zero cost
+- **Node.js 18+** for graphify and GitNexus
+- **Obsidian 1.6+** with the Bases core plugin (for visual wiki browsing)
+- **Docker** for Qdrant (SQLite FTS5 is the default and works out of the box)
+
+## Quick start
+
+```bash
+pip install "memorymaster[mcp]"
+memorymaster --db memorymaster.db init-db
+memorymaster-setup     # interactive: hooks, MCP, steward cron, CLAUDE.md / AGENTS.md
+```
+
+That's enough to use the CLI, the MCP server, and the auto-ingest Stop hook.
+
+```bash
+# Ingest a claim with citation
+memorymaster --db memorymaster.db ingest \
+  --text "Server uses PostgreSQL 16" \
+  --source "session://chat|turn-3|user confirmed"
+
+# Query memory (hybrid retrieval)
+memorymaster --db memorymaster.db query "database version" --retrieval-mode hybrid
+
+# Context optimizer — the killer feature for agents
+memorymaster --db memorymaster.db context "auth patterns" --budget 4000 --format xml
+
+# Run validation cycle
+memorymaster --db memorymaster.db run-cycle
+```
+
+For the one-prompt agent install (paste into any agent with shell access), see [`docs/handbook.md#one-prompt-agent-install`](docs/handbook.md#one-prompt-agent-install).
+
+## Pick your LLM provider
+
+| Provider | Env vars | Default model | Cost |
+|----------|----------|---------------|------|
+| **Claude Code OAuth** (recommended for subscribers) | `MEMORYMASTER_LLM_PROVIDER=claude_cli` (requires `claude` CLI on PATH) | `claude-haiku-4-5-20251001` | included in Claude Code plan |
+| Google Gemini (default) | `MEMORYMASTER_LLM_PROVIDER=google` + `GEMINI_API_KEY=...` | `gemini-3.1-flash-lite-preview` | ~free |
+| OpenAI | `MEMORYMASTER_LLM_PROVIDER=openai` + `OPENAI_API_KEY=...` | `gpt-4o-mini` | ~$0.001/call |
+| Anthropic API | `MEMORYMASTER_LLM_PROVIDER=anthropic` + `ANTHROPIC_API_KEY=...` | `claude-haiku-4-5-20251001` | ~$0.001/call |
+| Ollama (local) | `MEMORYMASTER_LLM_PROVIDER=ollama` + `OLLAMA_URL=http://localhost:11434` | `llama3.2:3b` | free |
+
+The `claude_cli` provider shells out to your local `claude --print` binary, so it inherits the OAuth session you're already logged into in Claude Code — no API key, no rotator, no quota juggling. **Caveat**: cold-start adds 3-15s per call (subprocess spawn), so it's ideal for batched/cron paths (steward, wiki-absorb) and not for latency-sensitive recall. Override with `MEMORYMASTER_CLAUDE_CLI_BIN` and `MEMORYMASTER_CLAUDE_CLI_TIMEOUT`. On VM installs the OAuth token expires ~24h, so pair with `MEMORYMASTER_LLM_FALLBACK_PROVIDER=ollama`; desktop tokens don't expire.
+
+For zero-cost offline use, install [Ollama](https://ollama.com), `ollama pull llama3.2:3b`, and set `MEMORYMASTER_LLM_PROVIDER=ollama`.
+
+## MCP server
+
+```json
+{
+  "mcpServers": {
+    "memorymaster": {
+      "command": "memorymaster-mcp",
+      "env": {
+        "MEMORYMASTER_DEFAULT_DB": "/path/to/memorymaster.db",
+        "MEMORYMASTER_WORKSPACE": "/path/to/your/project"
+      }
+    }
+  }
+}
+```
+
+22 MCP tools: `init_db`, `ingest_claim`, `run_cycle`, `run_steward`, `classify_query`, `query_memory`, `query_for_context`, `list_claims`, `redact_claim_payload`, `pin_claim`, `compact_memory`, `list_events`, `search_verbatim`, `open_dashboard`, `list_steward_proposals`, `resolve_steward_proposal`, `extract_entities`, `entity_stats`, `find_related_claims`, `quality_scores`, `recompute_tiers`, `federated_query`.
+
+See [`.mcp.json.example`](.mcp.json.example) for the full template.
+
+## Backends
+
+| Backend | Install | Use case |
+|---------|---------|----------|
+| **SQLite** | Built-in | Local development, single-agent, zero-config |
+| **Postgres** | `pip install "memorymaster[postgres]"` | Team deployment, multi-agent, pgvector search |
+
+## Docker Compose
+
+Run the full stack (MemoryMaster + Qdrant + Ollama) with one command:
+
+```bash
+docker compose up -d
+```
+
+See [INSTALLATION.md](INSTALLATION.md) for Kubernetes / Helm.
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev,mcp,security,embeddings,qdrant]"
+
+# Run tests
+pytest tests/ -q
+
+# Lint and format
+ruff check memorymaster/ && ruff format memorymaster/
+
+# Performance benchmarks
+python benchmarks/perf_smoke.py
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow.
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [docs/handbook.md](docs/handbook.md) | Full operator handbook — hooks, dashboard, steward, dream bridge, troubleshooting, one-prompt install |
+| [INSTALLATION.md](INSTALLATION.md) | Setup guide: pip, Docker, Helm, MCP config |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Dev setup, testing, PR workflow |
+| [ARCHITECTURE.md](ARCHITECTURE.md) | System design and subsystem details |
+| [USER_GUIDE.md](USER_GUIDE.md) | Usage, MCP integration, troubleshooting |
+| [CHANGELOG.md](CHANGELOG.md) | Version history and release notes |
+| [ROADMAP.md](ROADMAP.md) | Release plan and future tracks |
+| [docs/enabling-v2-systems.md](docs/enabling-v2-systems.md) | v3 statistical classifier + cadence policy opt-in |
+
+## License
+
+[MIT](LICENSE) — Built by [wolverin0](https://github.com/wolverin0)

memorymaster-3.5.1/README.md

@@ -0,0 +1,187 @@
+# MemoryMaster
+
+**Production-grade memory reliability system for AI coding agents.**
+
+Lifecycle-managed claims with citations, conflict detection, steward governance, hybrid retrieval, and MCP integration. Give your AI agents persistent, trustworthy memory.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Tests](https://img.shields.io/badge/tests-1029-green.svg)]()
+[![MCP Tools](https://img.shields.io/badge/MCP%20tools-22-purple.svg)]()
+[![CLI Commands](https://img.shields.io/badge/CLI%20commands-64-orange.svg)]()
+[![PyPI](https://img.shields.io/pypi/v/memorymaster.svg)](https://pypi.org/project/memorymaster/)
+
+MemoryMaster prevents the #1 problem with agent memory: **drift, stale assumptions, and unsafe disclosure**. It gives Claude Code, Codex, and any MCP-compatible agent persistent, verifiable memory with a full claim lifecycle, citation tracking, conflict detection, and human-in-the-loop governance.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Agent Runtime                            │
+│  (Claude Code / Codex / any MCP-compatible agent)               │
+└────────────┬────────────────────────────────┬───────────────────┘
+             │ MCP (22 tools)                 │ CLI (64 commands)
+             v                                v
+┌─────────────────────────────────────────────────────────────────┐
+│                      MemoryMaster Core                          │
+│  ┌──────────┐  ┌───────────┐  ┌──────────┐  ┌───────────────┐  │
+│  │ Ingestor │  │ Extractor │  │ Validator │  │ State Engine  │  │
+│  │ (events) │->│ (claims)  │->│ (probes)  │->│ (6-state FSM) │  │
+│  └──────────┘  └───────────┘  └──────────┘  └───────────────┘  │
+│  ┌──────────┐  ┌───────────┐  ┌──────────┐  ┌───────────────┐  │
+│  │ Retrieval│  │ Compactor │  │ Steward  │  │  Dashboard    │  │
+│  │ (hybrid) │  │ (archive) │  │ (govern) │  │  (HTML+SSE)   │  │
+│  └──────────┘  └───────────┘  └──────────┘  └───────────────┘  │
+└────────┬──────────────┬──────────────┬──────────┬───────────────┘
+         v              v              v          v
+   SQLite/Postgres   Qdrant      Ollama/CLI    Claude Code
+                    (vectors)   (LLM stack)   Auto Dream + Vault
+```
+
+## Key features
+
+- **6-state lifecycle**: `candidate` → `confirmed` → `stale` → `superseded` → `conflicted` → `archived`
+- **Citation tracking** with provenance for every claim
+- **Hybrid retrieval**: vector (sentence-transformers / Gemini) + FTS5 + freshness + confidence
+- **Context optimizer**: `query_for_context(budget=4000)` returns auto-curated memory that fits your token budget
+- **Entity graph** with typed relationships and alias resolution
+- **Steward governance**: multi-probe validators (filesystem, format, citation, semantic, tool) with proposal review
+- **Conflict resolution**: 5-tier auto (confidence > freshness > citations > LLM > manual)
+- **Auto-redaction** at ingest: JWT, GitHub tokens, Bearer, AWS keys, SSH keys, custom patterns
+- **LLM Wiki**: compiled-truth + append-only timeline articles with progressive-disclosure frontmatter
+- **Dual backend**: SQLite (zero-config) and Postgres (full feature parity with pgvector)
+- **Dream Bridge** for bidirectional sync with Claude Code's Auto Dream
+- **7-hook stack**: recall, classify, validate-wiki, session-start, auto-ingest, precompact, steward-cron
+
+Full feature index lives in [`docs/handbook.md`](docs/handbook.md).
+
+## Prerequisites
+
+**Required**
+
+- Python **3.10+** with `pip`
+- Claude Code, Codex, or any MCP-compatible agent
+
+**Optional**
+
+- **Already a Claude Code subscriber?** No API key needed — set `MEMORYMASTER_LLM_PROVIDER=claude_cli` and the steward + auto-ingest hooks will use your existing OAuth via the local `claude --print` binary
+- A free Gemini API key from [aistudio.google.com](https://aistudio.google.com) — powers the auto-ingest hook at ~zero cost
+- **Node.js 18+** for graphify and GitNexus
+- **Obsidian 1.6+** with the Bases core plugin (for visual wiki browsing)
+- **Docker** for Qdrant (SQLite FTS5 is the default and works out of the box)
+
+## Quick start
+
+```bash
+pip install "memorymaster[mcp]"
+memorymaster --db memorymaster.db init-db
+memorymaster-setup     # interactive: hooks, MCP, steward cron, CLAUDE.md / AGENTS.md
+```
+
+That's enough to use the CLI, the MCP server, and the auto-ingest Stop hook.
+
+```bash
+# Ingest a claim with citation
+memorymaster --db memorymaster.db ingest \
+  --text "Server uses PostgreSQL 16" \
+  --source "session://chat|turn-3|user confirmed"
+
+# Query memory (hybrid retrieval)
+memorymaster --db memorymaster.db query "database version" --retrieval-mode hybrid
+
+# Context optimizer — the killer feature for agents
+memorymaster --db memorymaster.db context "auth patterns" --budget 4000 --format xml
+
+# Run validation cycle
+memorymaster --db memorymaster.db run-cycle
+```
+
+For the one-prompt agent install (paste into any agent with shell access), see [`docs/handbook.md#one-prompt-agent-install`](docs/handbook.md#one-prompt-agent-install).
+
+## Pick your LLM provider
+
+| Provider | Env vars | Default model | Cost |
+|----------|----------|---------------|------|
+| **Claude Code OAuth** (recommended for subscribers) | `MEMORYMASTER_LLM_PROVIDER=claude_cli` (requires `claude` CLI on PATH) | `claude-haiku-4-5-20251001` | included in Claude Code plan |
+| Google Gemini (default) | `MEMORYMASTER_LLM_PROVIDER=google` + `GEMINI_API_KEY=...` | `gemini-3.1-flash-lite-preview` | ~free |
+| OpenAI | `MEMORYMASTER_LLM_PROVIDER=openai` + `OPENAI_API_KEY=...` | `gpt-4o-mini` | ~$0.001/call |
+| Anthropic API | `MEMORYMASTER_LLM_PROVIDER=anthropic` + `ANTHROPIC_API_KEY=...` | `claude-haiku-4-5-20251001` | ~$0.001/call |
+| Ollama (local) | `MEMORYMASTER_LLM_PROVIDER=ollama` + `OLLAMA_URL=http://localhost:11434` | `llama3.2:3b` | free |
+
+The `claude_cli` provider shells out to your local `claude --print` binary, so it inherits the OAuth session you're already logged into in Claude Code — no API key, no rotator, no quota juggling. **Caveat**: cold-start adds 3-15s per call (subprocess spawn), so it's ideal for batched/cron paths (steward, wiki-absorb) and not for latency-sensitive recall. Override with `MEMORYMASTER_CLAUDE_CLI_BIN` and `MEMORYMASTER_CLAUDE_CLI_TIMEOUT`. On VM installs the OAuth token expires ~24h, so pair with `MEMORYMASTER_LLM_FALLBACK_PROVIDER=ollama`; desktop tokens don't expire.
+
+For zero-cost offline use, install [Ollama](https://ollama.com), `ollama pull llama3.2:3b`, and set `MEMORYMASTER_LLM_PROVIDER=ollama`.
+
+## MCP server
+
+```json
+{
+  "mcpServers": {
+    "memorymaster": {
+      "command": "memorymaster-mcp",
+      "env": {
+        "MEMORYMASTER_DEFAULT_DB": "/path/to/memorymaster.db",
+        "MEMORYMASTER_WORKSPACE": "/path/to/your/project"
+      }
+    }
+  }
+}
+```
+
+22 MCP tools: `init_db`, `ingest_claim`, `run_cycle`, `run_steward`, `classify_query`, `query_memory`, `query_for_context`, `list_claims`, `redact_claim_payload`, `pin_claim`, `compact_memory`, `list_events`, `search_verbatim`, `open_dashboard`, `list_steward_proposals`, `resolve_steward_proposal`, `extract_entities`, `entity_stats`, `find_related_claims`, `quality_scores`, `recompute_tiers`, `federated_query`.
+
+See [`.mcp.json.example`](.mcp.json.example) for the full template.
+
+## Backends
+
+| Backend | Install | Use case |
+|---------|---------|----------|
+| **SQLite** | Built-in | Local development, single-agent, zero-config |
+| **Postgres** | `pip install "memorymaster[postgres]"` | Team deployment, multi-agent, pgvector search |
+
+## Docker Compose
+
+Run the full stack (MemoryMaster + Qdrant + Ollama) with one command:
+
+```bash
+docker compose up -d
+```
+
+See [INSTALLATION.md](INSTALLATION.md) for Kubernetes / Helm.
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev,mcp,security,embeddings,qdrant]"
+
+# Run tests
+pytest tests/ -q
+
+# Lint and format
+ruff check memorymaster/ && ruff format memorymaster/
+
+# Performance benchmarks
+python benchmarks/perf_smoke.py
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow.
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [docs/handbook.md](docs/handbook.md) | Full operator handbook — hooks, dashboard, steward, dream bridge, troubleshooting, one-prompt install |
+| [INSTALLATION.md](INSTALLATION.md) | Setup guide: pip, Docker, Helm, MCP config |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Dev setup, testing, PR workflow |
+| [ARCHITECTURE.md](ARCHITECTURE.md) | System design and subsystem details |
+| [USER_GUIDE.md](USER_GUIDE.md) | Usage, MCP integration, troubleshooting |
+| [CHANGELOG.md](CHANGELOG.md) | Version history and release notes |
+| [ROADMAP.md](ROADMAP.md) | Release plan and future tracks |
+| [docs/enabling-v2-systems.md](docs/enabling-v2-systems.md) | v3 statistical classifier + cadence policy opt-in |
+
+## License
+
+[MIT](LICENSE) — Built by [wolverin0](https://github.com/wolverin0)