memorymaster 1.0.0__tar.gz

memorymaster-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wolverin0
+
+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.

memorymaster-1.0.0/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.4
+Name: memorymaster
+Version: 1.0.0
+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: dev
+Requires-Dist: pytest>=8.2; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+Dynamic: license-file
+
+<p align="center">
+  <h1 align="center">MemoryMaster</h1>
+  <p align="center">
+    <strong>Production-grade memory reliability for AI coding agents</strong>
+  </p>
+  <p align="center">
+    <a href="https://github.com/wolverin0/memorymaster/actions/workflows/ci.yml"><img src="https://github.com/wolverin0/memorymaster/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+    <a href="https://github.com/wolverin0/memorymaster/releases"><img src="https://img.shields.io/github/v/release/wolverin0/memorymaster?color=blue" alt="Release"></a>
+    <a href="https://pypi.org/project/memorymaster/"><img src="https://img.shields.io/pypi/v/memorymaster?color=green" alt="PyPI"></a>
+    <a href="https://github.com/wolverin0/memorymaster/blob/main/LICENSE"><img src="https://img.shields.io/github/license/wolverin0/memorymaster" alt="License"></a>
+    <img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+">
+    <img src="https://img.shields.io/badge/tests-82%20passed-brightgreen" alt="Tests">
+    <img src="https://img.shields.io/badge/coverage-SQLite%20%2B%20Postgres-purple" alt="Backend Coverage">
+  </p>
+</p>
+
+---
+
+MemoryMaster gives AI coding agents **persistent, verifiable memory** with a full claim lifecycle, citation tracking, conflict detection, and human-in-the-loop governance. It prevents the #1 problem with agent memory: **drift, stale assumptions, and unsafe disclosure**.
+
+## Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **6-State Lifecycle** | `candidate` -> `confirmed` -> `stale` -> `superseded` -> `conflicted` -> `archived` |
+| **Citation Tracking** | Every claim links to source evidence with provenance |
+| **Hybrid Retrieval** | Lexical + vector + freshness + confidence ranking |
+| **Steward Governance** | Multi-probe validators with proposal/approve/reject workflow |
+| **MCP Integration** | 12 tools for Claude Code, Codex, and any MCP-compatible agent |
+| **Real-time Dashboard** | HTML UI with SSE streaming, conflict view, and triage actions |
+| **Auto-Redaction** | Tokens, keys, and passwords scrubbed at ingest time |
+| **Dual Backend** | SQLite (zero-config) and Postgres (with optional pgvector) |
+| **Incident Drills** | Automated perf + eval + integrity checks with HMAC-signed evidence |
+| **10+ Connectors** | Git, Slack, Jira, email, GitHub, and conversation imports |
+
+## Architecture
+
+```
+Agent Runtime
+  -> Event Ingestor -> Event Log (append-only)
+                      -> Claim Extractor -> Claims Store
+                      -> State Engine (6-state lifecycle)
+Steward Loop -> Multi-Probe Validators -> Proposals -> Human Review
+Operator Runtime -> JSONL Inbox -> Progressive Retrieval -> Maintenance
+Query Path -> Hybrid Ranker -> Response Context Builder
+Compactor -> Summaries + Citation Graph -> Archive
+```
+
+## Quick Start
+
+```bash
+pip install memorymaster
+```
+
+```bash
+# Initialize database
+memorymaster --db memory.db init-db
+
+# Ingest a claim with citation
+memorymaster --db memory.db ingest \
+  --text "Server IP is 10.0.0.2" \
+  --source "session://chat|turn-1|user confirmed"
+
+# Run validation cycle
+memorymaster --db memory.db run-cycle
+
+# Query memory
+memorymaster --db memory.db query "server ip" --retrieval-mode hybrid
+```
+
+## MCP Server (Claude Code / Codex)
+
+```bash
+pip install "memorymaster[mcp]"
+```
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "memorymaster": {
+      "command": "memorymaster-mcp"
+    }
+  }
+}
+```
+
+**12 MCP tools available:** `init_db`, `ingest_claim`, `run_cycle`, `query_memory`, `list_claims`, `list_events`, `pin_claim`, `compact_memory`, `run_steward`, `list_steward_proposals`, `resolve_steward_proposal`, `open_dashboard`
+
+## Operator Runtime
+
+Process conversation turns from a JSONL inbox with automatic claim extraction, retrieval, and maintenance:
+
+```bash
+memorymaster --db memory.db run-operator \
+  --inbox-jsonl turns.jsonl \
+  --retrieval-mode hybrid \
+  --policy-mode cadence \
+  --max-idle-seconds 120 \
+  --log-jsonl artifacts/operator/events.jsonl
+```
+
+Features: restart-safe checkpointing, durable pending-turn queue, progressive tiered retrieval, configurable maintenance cadence, `<private>...</private>` block exclusion.
+
+## Dashboard
+
+```bash
+memorymaster --db memory.db run-dashboard --port 8765
+```
+
+Open `http://127.0.0.1:8765/dashboard` for:
+- Claims table with status filters
+- Timeline feed with transition history
+- Conflict comparison view
+- Review queue with approve/reject actions
+- Live SSE operator event stream
+
+**API endpoints:** `/health`, `/api/claims`, `/api/events`, `/api/timeline`, `/api/conflicts`, `/api/review-queue`, `/api/triage/action`, `/api/operator/stream`
+
+## Steward Governance
+
+The steward probes confirmed claims for staleness using multiple validators:
+
+| Probe | What it checks |
+|-------|----------------|
+| `filesystem_grep` | Does the claim value appear in workspace files? |
+| `deterministic_format` | Is the object value well-formed (IP, URL, email, date)? |
+| `deterministic_citation_locator` | Do cited sources still exist and match? |
+| `semantic_probe` | Does surrounding context still support the claim? |
+| `tool_probe` | Does running the relevant tool confirm the value? |
+
+```bash
+# Non-destructive audit (proposals only)
+memorymaster --db memory.db --workspace . run-steward --mode manual --max-cycles 1
+
+# Apply transitions
+memorymaster --db memory.db --workspace . run-steward --mode manual --apply
+
+# Review and resolve proposals
+memorymaster --db memory.db steward-proposals --limit 50
+memorymaster --db memory.db resolve-proposal --action approve --claim-id 42
+```
+
+## Connectors
+
+Import from any source into the operator inbox:
+
+```bash
+# Git commits
+python scripts/git_to_turns.py --input export.json --output turns.jsonl
+
+# Slack messages
+python scripts/slack_live_to_turns.py --input config.json --output turns.jsonl
+
+# Jira issues
+python scripts/jira_live_to_turns.py --input config.json --output turns.jsonl
+
+# Email (IMAP)
+python scripts/email_live_to_turns.py --input config.json --output turns.jsonl
+
+# Generic AI conversations (OpenAI/Claude/Gemini)
+python scripts/conversation_importer.py --input chat.json --output turns.jsonl
+```
+
+## Security
+
+- **Auto-redaction**: Tokens, API keys, passwords, and secrets are scrubbed at ingest time
+- **Policy-gated access**: `--allow-sensitive` requires `MEMORYMASTER_ALLOW_SENSITIVE_BYPASS=1`
+- **Non-destructive redaction**: `redact-claim` scrubs claim/citation data with full audit trail
+- **Encryption**: Optional Fernet encryption for sensitive payloads (`pip install "memorymaster[security]"`)
+
+## Performance
+
+SLO-driven benchmarks with configurable profiles:
+
+| Metric | Quick Profile | Production Profile |
+|--------|--------------|-------------------|
+| Ingest p95 | <= 60ms | <= 80ms |
+| Ingest throughput | >= 80 ops/sec | >= 60 ops/sec |
+| Query p95 | <= 250ms | <= 400ms |
+| Query throughput | >= 12 ops/sec | >= 8 ops/sec |
+| Cycle p95 | <= 3.5s | <= 6.0s |
+| End-to-end runtime | <= 20s | <= 45s |
+
+```bash
+python benchmarks/perf_smoke.py --slo-config benchmarks/slo_targets.json
+```
+
+## 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 |
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev,mcp,security]"
+
+# Run tests
+pytest tests/ -q
+
+# Run performance benchmarks
+python benchmarks/perf_smoke.py
+
+# Run evaluation suite
+python scripts/eval_memorymaster.py --strict
+
+# Run incident drill
+python scripts/run_incident_drill.py --dry-run
+```
+
+## Project Stats
+
+- **22 source modules** (10,000+ lines)
+- **82 tests** across 21 test modules
+- **24 utility scripts** (connectors, benchmarks, drills)
+- **12 MCP tools** for agent integration
+- **6 API endpoints** + SSE streaming
+- **10+ import connectors** (Git, Slack, Jira, email, GitHub, conversations)
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [ARCHITECTURE.md](ARCHITECTURE.md) | System design and subsystem details |
+| [ROADMAP.md](ROADMAP.md) | Release plan and future tracks |
+| [CHANGELOG.md](CHANGELOG.md) | Version history and release notes |
+| [USER_GUIDE.md](USER_GUIDE.md) | Setup, usage, MCP integration, troubleshooting |
+
+## License
+
+[MIT](LICENSE) - Built by [wolverin0](https://github.com/wolverin0)

memorymaster-1.0.0/README.md

@@ -0,0 +1,236 @@
+<p align="center">
+  <h1 align="center">MemoryMaster</h1>
+  <p align="center">
+    <strong>Production-grade memory reliability for AI coding agents</strong>
+  </p>
+  <p align="center">
+    <a href="https://github.com/wolverin0/memorymaster/actions/workflows/ci.yml"><img src="https://github.com/wolverin0/memorymaster/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+    <a href="https://github.com/wolverin0/memorymaster/releases"><img src="https://img.shields.io/github/v/release/wolverin0/memorymaster?color=blue" alt="Release"></a>
+    <a href="https://pypi.org/project/memorymaster/"><img src="https://img.shields.io/pypi/v/memorymaster?color=green" alt="PyPI"></a>
+    <a href="https://github.com/wolverin0/memorymaster/blob/main/LICENSE"><img src="https://img.shields.io/github/license/wolverin0/memorymaster" alt="License"></a>
+    <img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+">
+    <img src="https://img.shields.io/badge/tests-82%20passed-brightgreen" alt="Tests">
+    <img src="https://img.shields.io/badge/coverage-SQLite%20%2B%20Postgres-purple" alt="Backend Coverage">
+  </p>
+</p>
+
+---
+
+MemoryMaster gives AI coding agents **persistent, verifiable memory** with a full claim lifecycle, citation tracking, conflict detection, and human-in-the-loop governance. It prevents the #1 problem with agent memory: **drift, stale assumptions, and unsafe disclosure**.
+
+## Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **6-State Lifecycle** | `candidate` -> `confirmed` -> `stale` -> `superseded` -> `conflicted` -> `archived` |
+| **Citation Tracking** | Every claim links to source evidence with provenance |
+| **Hybrid Retrieval** | Lexical + vector + freshness + confidence ranking |
+| **Steward Governance** | Multi-probe validators with proposal/approve/reject workflow |
+| **MCP Integration** | 12 tools for Claude Code, Codex, and any MCP-compatible agent |
+| **Real-time Dashboard** | HTML UI with SSE streaming, conflict view, and triage actions |
+| **Auto-Redaction** | Tokens, keys, and passwords scrubbed at ingest time |
+| **Dual Backend** | SQLite (zero-config) and Postgres (with optional pgvector) |
+| **Incident Drills** | Automated perf + eval + integrity checks with HMAC-signed evidence |
+| **10+ Connectors** | Git, Slack, Jira, email, GitHub, and conversation imports |
+
+## Architecture
+
+```
+Agent Runtime
+  -> Event Ingestor -> Event Log (append-only)
+                      -> Claim Extractor -> Claims Store
+                      -> State Engine (6-state lifecycle)
+Steward Loop -> Multi-Probe Validators -> Proposals -> Human Review
+Operator Runtime -> JSONL Inbox -> Progressive Retrieval -> Maintenance
+Query Path -> Hybrid Ranker -> Response Context Builder
+Compactor -> Summaries + Citation Graph -> Archive
+```
+
+## Quick Start
+
+```bash
+pip install memorymaster
+```
+
+```bash
+# Initialize database
+memorymaster --db memory.db init-db
+
+# Ingest a claim with citation
+memorymaster --db memory.db ingest \
+  --text "Server IP is 10.0.0.2" \
+  --source "session://chat|turn-1|user confirmed"
+
+# Run validation cycle
+memorymaster --db memory.db run-cycle
+
+# Query memory
+memorymaster --db memory.db query "server ip" --retrieval-mode hybrid
+```
+
+## MCP Server (Claude Code / Codex)
+
+```bash
+pip install "memorymaster[mcp]"
+```
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "memorymaster": {
+      "command": "memorymaster-mcp"
+    }
+  }
+}
+```
+
+**12 MCP tools available:** `init_db`, `ingest_claim`, `run_cycle`, `query_memory`, `list_claims`, `list_events`, `pin_claim`, `compact_memory`, `run_steward`, `list_steward_proposals`, `resolve_steward_proposal`, `open_dashboard`
+
+## Operator Runtime
+
+Process conversation turns from a JSONL inbox with automatic claim extraction, retrieval, and maintenance:
+
+```bash
+memorymaster --db memory.db run-operator \
+  --inbox-jsonl turns.jsonl \
+  --retrieval-mode hybrid \
+  --policy-mode cadence \
+  --max-idle-seconds 120 \
+  --log-jsonl artifacts/operator/events.jsonl
+```
+
+Features: restart-safe checkpointing, durable pending-turn queue, progressive tiered retrieval, configurable maintenance cadence, `<private>...</private>` block exclusion.
+
+## Dashboard
+
+```bash
+memorymaster --db memory.db run-dashboard --port 8765
+```
+
+Open `http://127.0.0.1:8765/dashboard` for:
+- Claims table with status filters
+- Timeline feed with transition history
+- Conflict comparison view
+- Review queue with approve/reject actions
+- Live SSE operator event stream
+
+**API endpoints:** `/health`, `/api/claims`, `/api/events`, `/api/timeline`, `/api/conflicts`, `/api/review-queue`, `/api/triage/action`, `/api/operator/stream`
+
+## Steward Governance
+
+The steward probes confirmed claims for staleness using multiple validators:
+
+| Probe | What it checks |
+|-------|----------------|
+| `filesystem_grep` | Does the claim value appear in workspace files? |
+| `deterministic_format` | Is the object value well-formed (IP, URL, email, date)? |
+| `deterministic_citation_locator` | Do cited sources still exist and match? |
+| `semantic_probe` | Does surrounding context still support the claim? |
+| `tool_probe` | Does running the relevant tool confirm the value? |
+
+```bash
+# Non-destructive audit (proposals only)
+memorymaster --db memory.db --workspace . run-steward --mode manual --max-cycles 1
+
+# Apply transitions
+memorymaster --db memory.db --workspace . run-steward --mode manual --apply
+
+# Review and resolve proposals
+memorymaster --db memory.db steward-proposals --limit 50
+memorymaster --db memory.db resolve-proposal --action approve --claim-id 42
+```
+
+## Connectors
+
+Import from any source into the operator inbox:
+
+```bash
+# Git commits
+python scripts/git_to_turns.py --input export.json --output turns.jsonl
+
+# Slack messages
+python scripts/slack_live_to_turns.py --input config.json --output turns.jsonl
+
+# Jira issues
+python scripts/jira_live_to_turns.py --input config.json --output turns.jsonl
+
+# Email (IMAP)
+python scripts/email_live_to_turns.py --input config.json --output turns.jsonl
+
+# Generic AI conversations (OpenAI/Claude/Gemini)
+python scripts/conversation_importer.py --input chat.json --output turns.jsonl
+```
+
+## Security
+
+- **Auto-redaction**: Tokens, API keys, passwords, and secrets are scrubbed at ingest time
+- **Policy-gated access**: `--allow-sensitive` requires `MEMORYMASTER_ALLOW_SENSITIVE_BYPASS=1`
+- **Non-destructive redaction**: `redact-claim` scrubs claim/citation data with full audit trail
+- **Encryption**: Optional Fernet encryption for sensitive payloads (`pip install "memorymaster[security]"`)
+
+## Performance
+
+SLO-driven benchmarks with configurable profiles:
+
+| Metric | Quick Profile | Production Profile |
+|--------|--------------|-------------------|
+| Ingest p95 | <= 60ms | <= 80ms |
+| Ingest throughput | >= 80 ops/sec | >= 60 ops/sec |
+| Query p95 | <= 250ms | <= 400ms |
+| Query throughput | >= 12 ops/sec | >= 8 ops/sec |
+| Cycle p95 | <= 3.5s | <= 6.0s |
+| End-to-end runtime | <= 20s | <= 45s |
+
+```bash
+python benchmarks/perf_smoke.py --slo-config benchmarks/slo_targets.json
+```
+
+## 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 |
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev,mcp,security]"
+
+# Run tests
+pytest tests/ -q
+
+# Run performance benchmarks
+python benchmarks/perf_smoke.py
+
+# Run evaluation suite
+python scripts/eval_memorymaster.py --strict
+
+# Run incident drill
+python scripts/run_incident_drill.py --dry-run
+```
+
+## Project Stats
+
+- **22 source modules** (10,000+ lines)
+- **82 tests** across 21 test modules
+- **24 utility scripts** (connectors, benchmarks, drills)
+- **12 MCP tools** for agent integration
+- **6 API endpoints** + SSE streaming
+- **10+ import connectors** (Git, Slack, Jira, email, GitHub, conversations)
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [ARCHITECTURE.md](ARCHITECTURE.md) | System design and subsystem details |
+| [ROADMAP.md](ROADMAP.md) | Release plan and future tracks |
+| [CHANGELOG.md](CHANGELOG.md) | Version history and release notes |
+| [USER_GUIDE.md](USER_GUIDE.md) | Setup, usage, MCP integration, troubleshooting |
+
+## License
+
+[MIT](LICENSE) - Built by [wolverin0](https://github.com/wolverin0)