m3-memory 2026.4.6__tar.gz

m3_memory-2026.4.6/ARCHITECTURE.md

@@ -0,0 +1,222 @@
+# 🛠️ <img src="docs/icon.svg" height="60" style="vertical-align: baseline; margin-bottom: -15px;"> Memory — Agent Instructions
+
+
+> **`M3_MEMORY_ROOT`** — the root of the `m3-memory` repository checkout.
+
+> **Local overrides:** If `LOCAL_RULES.md` exists at `$M3_MEMORY_ROOT/LOCAL_RULES.md`, read it before proceeding. It contains machine-specific failover rules (embedding endpoints, LLM endpoints, internal IPs). It is git-ignored and never committed.
+
+> All paths are relative to `$M3_MEMORY_ROOT` unless otherwise noted.
+>
+> This file is symlinked to `~/.claude/CLAUDE.md` and `~/.gemini/GEMINI.md`.
+> Follow these instructions exactly. For technical implementation details, see [TECHNICAL_DETAILS.md](./TECHNICAL_DETAILS.md).
+
+---
+
+## 🛠️ Memory Tools — When and How to Use
+
+### ✍️ Writing Memories
+
+**Tool:** `memory → memory_write`
+
+Call `memory_write` to persist any fact, decision, preference, observation, or knowledge that should survive beyond the current conversation.
+
+| Parameter | Required | Notes |
+|-----------|----------|-------|
+| `type` | Yes | One of: `note`, `fact`, `decision`, `preference`, `task`, `code`, `config`, `observation`, `plan`, `summary`, `snippet`, `reference`, `log`, `home`, `user_fact`, `scratchpad`, `auto` |
+| `content` | Yes | The memory content (max 50,000 chars) |
+| `title` | No | Short descriptive title — used for contradiction matching |
+| `importance` | No | 0.0–1.0 (default 0.5). Higher = slower decay, higher search ranking |
+| `agent_id` | No | Your agent identifier |
+| `user_id` | No | User identifier for multi-user isolation |
+| `scope` | No | `user`, `session`, `agent` (default), or `org` |
+| `valid_from` | No | When this fact became true (ISO 8601). Defaults to now. |
+| `valid_to` | No | When this fact stopped being true (ISO 8601). Empty = still valid. |
+| `embed` | No | Generate embedding for semantic search (default true) |
+| `metadata` | No | JSON string with tags, categories, or custom fields |
+
+**Type selection guide:**
+- `fact` — objective truths about the world or system ("PostgreSQL 15 is the warehouse version")
+- `decision` — choices made by the user or system ("We chose SQLite over DuckDB for local storage")
+- `preference` — user preferences ("User prefers dark mode", "User wants terse responses")
+- `observation` — things noticed but not yet confirmed ("Build times seem slower after the migration")
+- `note` — general-purpose when no specific type fits
+- `auto` — let the local LLM classify the type automatically
+
+**Automatic behaviors on write:**
+
+```mermaid
+graph TD
+    W[memory_write] --> S[Safety Check]
+    S -->|Pass| E[Generate Embedding]
+    E --> C[Contradiction Detection]
+    E --> L[Auto-Linking]
+    C -->|New| DB[(SQLite)]
+    C -->|Conflict| SUP[Supersede Old]
+    SUP --> DB
+    L --> DB
+    W --> H[SHA-256 Hash]
+    H --> DB
+```
+
+- Contradiction detection runs automatically — if a same-type, same-title memory exists with different content (cosine > 0.85), the old one is superseded
+- Auto-linking connects the new memory to the most related existing memory (cosine > 0.7)
+- Content safety check rejects XSS, SQL injection, Python injection, and prompt injection
+- SHA-256 content hash is computed and stored for tamper detection
+- Session-scoped memories auto-expire after 24 hours
+
+### 🔍 Searching Memories
+
+**Tool:** `memory → memory_search`
+
+Always search before writing to avoid duplicates. Search before starting any new task (Protocol #4).
+
+```mermaid
+graph LR
+    Q[Query] --> FTS[Stage 1: FTS5 Keywords]
+    Q --> VEC[Stage 2: Vector Similarity]
+    FTS --> COMB[Combined Score]
+    VEC --> COMB
+    COMB --> MMR[Stage 3: MMR Re-Ranking]
+    MMR --> R[Final Top-K Results]
+```
+
+| Parameter | Required | Notes |
+|-----------|----------|-------|
+| `query` | Yes | Natural language query (max 2,000 chars) |
+| `k` | No | Number of results (default 8, max 100) |
+| `type_filter` | No | Filter by type. Quote for exact match: `"fact"` |
+| `agent_filter` | No | Filter by agent_id |
+| `user_id` | No | Filter by user |
+| `scope` | No | Filter by scope |
+| `as_of` | No | Point-in-time query: "what was true as of this date?" (ISO 8601) |
+| `search_mode` | No | `hybrid` (default) or `semantic` |
+
+**How search works:** FTS5 keyword matching → vector similarity → MMR diversity re-ranking. Results are scored as `0.7 × vector + 0.3 × BM25`. If FTS returns nothing, falls back to pure semantic search automatically.
+
+**Tool:** `memory → memory_suggest`
+
+Use `memory_suggest` instead of `memory_search` when you need to explain WHY results were retrieved. Returns score breakdowns (vector, BM25, MMR penalty) per result.
+
+### 📝 Retrieving and Modifying
+
+| Tool | When to Use |
+|------|-------------|
+| `memory_get(id)` | Retrieve full memory by UUID |
+| `memory_update(id, ...)` | Update content, title, metadata, or importance. Records audit trail. |
+| `memory_delete(id)` | Soft-delete (default, recoverable) or `hard=True` (cascade deletes embeddings, relationships, history) |
+| `memory_verify(id)` | Check content integrity — re-computes SHA-256 and compares to stored hash |
+
+### 🕸️ Knowledge Graph
+
+| Tool | When to Use |
+|------|-------------|
+| `memory_link(from_id, to_id, type)` | Create a relationship. Types: `related`, `supports`, `contradicts`, `extends`, `supersedes`, `references`, `consolidates` |
+| `memory_graph(id, depth)` | Explore connected memories up to 3 hops. Use when context around a memory matters. |
+| `memory_history(id)` | View the full audit trail for a memory — every create, update, delete, supersede event |
+
+### 💬 Conversations
+
+| Tool | When to Use |
+|------|-------------|
+| `conversation_start(title, ...)` | Begin a new conversation thread |
+| `conversation_append(conversation_id, role, content)` | Add a message to a conversation |
+| `conversation_search(query)` | Search across all conversation messages |
+| `conversation_summarize(conversation_id, threshold)` | Generate an LLM summary when a conversation has many messages |
+
+### ♻️ Lifecycle and Maintenance
+
+| Tool | When to Use |
+|------|-------------|
+| `memory_maintenance()` | Run decay, expiry purge, orphan pruning, auto-archival, retention enforcement. Call periodically or when system feels sluggish. |
+| `memory_dedup(threshold, dry_run)` | Find near-duplicate memories. Use `dry_run=True` first to preview. |
+| `memory_consolidate(type_filter, agent_filter, threshold)` | Merge old memories of the same type into LLM-generated summaries. Use when a category has too many items. |
+| `memory_set_retention(agent_id, max_memories, ttl_days)` | Set per-agent retention limits. Enforced automatically by `memory_maintenance`. |
+| `memory_feedback(memory_id, feedback)` | Mark a memory as `useful` (boosts importance +0.1) or `wrong` (soft-deletes). |
+
+### ⚖️ Data Governance
+
+| Tool | When to Use |
+|------|-------------|
+| `gdpr_export(user_id)` | User requests their data — returns all memories as JSON |
+| `gdpr_forget(user_id)` | User requests deletion — hard-deletes everything (memories, embeddings, relationships, history) |
+| `memory_export(agent_filter, type_filter, since)` | Export memories as portable JSON for backup or migration |
+| `memory_import(data)` | Import from a previous export. UPSERT semantics — safe to re-run. |
+
+### ⚙️ Operations
+
+| Tool | When to Use |
+|------|-------------|
+| `memory_cost_report()` | Check session operation counts (embed calls, tokens, searches, writes) |
+| `chroma_sync(direction)` | Manual sync with ChromaDB. Use `push`, `pull`, or `both`. |
+
+---
+
+## MCP Bridge Infrastructure
+
+| Server | Script | Tools |
+|--------|--------|-------|
+| `custom_pc_tool` | `bin/custom_tool_bridge.py` | `log_activity`, `update_focus`, `query_decisions`, `retire_focus`, `check_thermal_load`, `query_local_model`, `web_search`, `grok_ask` |
+| `memory` | `bin/memory_bridge.py` | 25 memory tools (see above) |
+| `grok_intel` | `bin/grok_bridge.py` | `grok_ask` — real-time X/Twitter data via Grok 3 |
+| `web_research` | `bin/web_research_bridge.py` | `web_search` — Perplexity sonar-pro (auto-fallback to Grok on failure) |
+| `mcp_proxy` | `bin/mcp_proxy.py` | SSE streaming proxy for non-MCP-native clients |
+| `debug_agent` | `bin/debug_agent_bridge.py` | `debug_analyze`, `debug_bisect`, `debug_trace`, `debug_correlate`, `debug_history`, `debug_report` |
+
+**Local model calls:** Use `custom_pc_tool → query_local_model(prompt=...)` to invoke the local LLM directly.
+
+**LLM Engine:** `bin/llm_failover.py` auto-selects the largest available model. Default: `localhost:1234`. For multi-machine setups, set `LLM_ENDPOINTS_CSV` env var with comma-separated endpoints.
+
+---
+
+## 📑 Operational Protocols — MANDATORY, NO EXCEPTIONS
+
+Every protocol specifies the **exact MCP server and tool** to call. Do not batch; fire immediately.
+
+### 🧠 Protocol #1 — The Reasoning Rule
+**Trigger:** `query_local_model` returns `reasoning_content` (>200 chars).
+**Action:** Automatically archived to `activity_logs` by `query_local_model`. For manual complex reasoning, call `custom_pc_tool → log_activity(category="thought", ...)`.
+
+### 🌡️ Protocol #2 — The Hardware Rule
+**Trigger:** Suspected pressure or after heavy inference.
+**Action:** 1. `custom_pc_tool → check_thermal_load()`. 2. If status ≠ Nominal, `log_activity(category="hardware", ...)`.
+
+### ⚖️ Protocol #3 — The Decision Rule
+**Trigger:** User agrees to ANY change (code, file move, diagnosis).
+**Action:** Call `custom_pc_tool → log_activity(category="decision", ...)` immediately.
+
+### 🔍 Protocol #4 — The Search Rule
+**Trigger:** Before starting any new task.
+**Action:** Call `custom_pc_tool → query_decisions(...)` **AND** `memory → memory_search(...)`. Check what's already known before proceeding.
+
+### 🎯 Protocol #5 — The Focus Protocol
+**Trigger:** Every 3 turns of a technical conversation.
+**Action:** `custom_pc_tool → update_focus(summary="...")`. Call `retire_focus()` on task completion.
+
+---
+
+## Auth Model
+
+All bridges resolve API keys using `$M3_MEMORY_ROOT/bin/auth_utils.py`:
+1. Environment variables
+2. `keyring` (Keychain / Credential Manager)
+3. **Synchronized Encrypted Vault** (AES-256 via Fernet/PBKDF2-HMAC-SHA256, 600K iterations, synced to PG Warehouse)
+
+**Security:** `AGENT_OS_MASTER_KEY` must be in native OS keyring. API keys are NEVER stored in plaintext. Legacy 100K-iteration encrypted secrets are auto-migrated to 600K on first decryption.
+
+---
+
+## Sandbox Environment
+
+**OpenClaw** — containerized agent sandbox (node:22-slim) on `localhost:8000`.
+- Tools: `claw-grok`, `claw-claude`, `claw-gemini`, `claw-perplexity`, `claw-local`
+- Full LAN access via OrbStack (can reach ChromaDB/Postgres)
+
+---
+
+## Health Check
+
+```bash
+bin/mcp_check.sh                    # MCP bridge connectivity
+python bin/test_memory_bridge.py    # 41 end-to-end tests
+python bin/benchmark_memory.py      # Retrieval quality benchmarks
+```

m3_memory-2026.4.6/LICENSE

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

m3_memory-2026.4.6/PKG-INFO

@@ -0,0 +1,336 @@
+Metadata-Version: 2.4
+Name: m3-memory
+Version: 2026.4.6
+Summary: Local-first agentic memory layer for MCP agents — 25 tools, hybrid search, GDPR, no cloud
+Author: skynetcmd
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/skynetcmd/m3-memory
+Project-URL: Repository, https://github.com/skynetcmd/m3-memory
+Project-URL: Bug Tracker, https://github.com/skynetcmd/m3-memory/issues
+Project-URL: Changelog, https://github.com/skynetcmd/m3-memory/blob/main/CHANGELOG.md
+Keywords: mcp,model-context-protocol,agentic-memory,local-llm,claude,gemini,rag,vector-search,sqlite,gdpr,ai-agents,ollama
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 🧠 M3 Memory — Local-First Agentic Memory for MCP Agents
+
+<p align="center">
+  <img src="docs/logo.svg" alt="M3 Memory Logo" width="600">
+</p>
+
+<p align="center">
+  <a href="https://github.com/skynetcmd/m3-memory/stargazers"><img alt="GitHub Stars" src="https://img.shields.io/github/stars/skynetcmd/m3-memory?style=social"></a>
+  <a href="https://github.com/skynetcmd/m3-memory/network/members"><img alt="GitHub Forks" src="https://img.shields.io/github/forks/skynetcmd/m3-memory?style=social"></a>
+  <a href="https://discord.gg/ZcJ3EGC99B"><img alt="Discord" src="https://img.shields.io/badge/Discord-M3--Memory%20Community-5865F2?logo=discord&logoColor=white"></a>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/m3-memory/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/m3-memory.svg"></a>
+  <a href="https://pypi.org/project/m3-memory/"><img alt="PyPI downloads" src="https://img.shields.io/pypi/dm/m3-memory.svg"></a>
+  <a href="https://www.python.org"><img alt="Python 3.11+" src="https://img.shields.io/badge/Python-3.11+-blue.svg"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green.svg"></a>
+  <a href="https://modelcontextprotocol.io"><img alt="MCP 25 tools" src="https://img.shields.io/badge/MCP-25_tools-orange.svg"></a>
+  <a href=".github/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/badge/CI-lint%20%7C%20typecheck%20%7C%20test-brightgreen.svg"></a>
+  <img alt="Platform" src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey.svg">
+</p>
+
+> Give your MCP agents persistent, private memory that actually works. No cloud. No forgetting.
+
+**Industrial-strength memory layer that just works.** M3 Memory gives AI agents persistent, private, intelligent memory — running 100% on your hardware, with no cloud APIs and no subscriptions.
+
+- 🛠️ **25 MCP tools** — write, search, link, graph, verify, sync, export, and more
+- 🔍 **Hybrid search** — FTS5 keywords + vector similarity + MMR diversity re-ranking
+- 🚫 **Contradiction detection** — stale facts are superseded automatically
+- 🔄 **Cross-device sync** — SQLite ↔ PostgreSQL ↔ ChromaDB, bi-directional
+- 🛡️ **GDPR-ready** — Article 17 (forget) and Article 20 (export) built in
+- 🔒 **Fully local** — your embeddings, your hardware, your data
+
+Works with **Claude Code, Gemini CLI, Aider, OpenClaw**, or any MCP-compatible agent.
+
+⭐ **Star if you want local agents that remember** — feedback & issues very welcome!
+
+---
+
+## Table of Contents
+
+- [Why M3 Memory](#why-m3-memory)
+- [Architecture](#architecture)
+- [Quick Start](#quick-start)
+- [Features](#features)
+- [25 MCP Tools](#25-mcp-tools)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+
+---
+
+## Why M3 Memory
+
+Most agent memory solutions require you to pick one: local speed, or cloud persistence, or multi-agent sharing. M3 Memory gives you all three, with zero data leaving your machine by default.
+
+**Example:** You're debugging a deployment issue on your MacBook at a coffee shop. Claude Code recalls the architecture decisions from last week, the server configs from yesterday, and the troubleshooting steps that worked before — all from local SQLite, no internet required. Later, at your Windows desktop at home, Gemini CLI picks up exactly where you left off. Same memories, same context, same knowledge graph — synced in the background the moment your laptop hit the local network.
+
+> ⭐ **Your AI's memory belongs to you, lives on your hardware, and follows you across every device and every agent.**
+
+---
+
+## Architecture
+
+```mermaid
+graph TD
+    subgraph "🤖 AI Agents"
+        C[Claude Code]
+        G[Gemini CLI]
+        A[Aider / OpenClaw]
+    end
+
+    subgraph "🌉 MCP Bridge"
+        MB[memory_bridge.py — 25 MCP tools]
+    end
+
+    subgraph "💾 Storage Layers"
+        SQ[(SQLite — Local L1)]
+        PG[(PostgreSQL — Sync L2)]
+        CH[(ChromaDB — Federated L3)]
+    end
+
+    C & G & A <--> MB
+    MB <--> SQ
+    SQ <-->|Bi-directional Delta Sync| PG
+    SQ <-->|Push/Pull| CH
+```
+
+### The Memory Write Pipeline
+
+```mermaid
+sequenceDiagram
+    participant A as Agent
+    participant M as M3 Memory
+    participant L as Local LLM
+    participant S as SQLite
+
+    A->>M: memory_write(content)
+    M->>M: Safety Check (XSS / injection / poisoning)
+    M->>L: Generate Embedding
+    L-->>M: Vector [0.12, -0.05, ...]
+    M->>M: Contradiction Detection
+    M->>M: Auto-Link Related Memories
+    M->>M: SHA-256 Content Hash
+    M->>S: Store Memory + Vector
+    S-->>M: Success
+    M-->>A: Created: <uuid>
+```
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.11+
+- Any OpenAI-compatible local LLM server: [LM Studio](https://lmstudio.ai), [Ollama](https://ollama.com), vLLM, LocalAI, llama.cpp
+- *(Optional)* PostgreSQL + ChromaDB for full cross-device federation
+
+### Install
+
+**Option A — pip (quickest):**
+```bash
+pip install m3-memory
+```
+
+**Option B — clone (for development or full feature set):**
+```bash
+git clone https://github.com/skynetcmd/m3-memory.git
+cd m3-memory
+
+python -m venv .venv
+source .venv/bin/activate          # macOS/Linux
+# .\.venv\Scripts\Activate.ps1    # Windows PowerShell
+
+pip install -r requirements.txt
+```
+
+### Validate & Test
+
+```bash
+python validate_env.py             # Check all dependencies and LLM connectivity
+python run_tests.py                # Run the end-to-end test suite
+```
+
+### Connect Your Agent
+
+Copy [`mcp.json.example`](./mcp.json.example) to your agent's MCP config location and update the `cwd` path:
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "python",
+      "args": ["bin/memory_bridge.py"],
+      "cwd": "/path/to/m3-memory"
+    }
+  }
+}
+```
+
+| Agent | Config location |
+|-------|----------------|
+| Claude Code | `~/.claude/claude_desktop_config.json` or `.mcp.json` in project root |
+| Gemini CLI | `~/.gemini/settings.json` |
+| Aider | `.aider.conf.yml` (via `--mcp-server` flag) |
+
+For OS-specific setup: [macOS](./docs/install_macos.md) | [Linux](./docs/install_linux.md) | [Windows](./docs/install_windows-powershell.md)
+
+> M3 Memory can also be discovered automatically in Claude Code and other MCP clients via the [MCP Registry](https://github.com/modelcontextprotocol/registry). See [`mcp-server.json`](./mcp-server.json) for the registry manifest.
+
+---
+
+## Features
+
+### 🔍 Hybrid Search That Actually Works
+
+Three-stage pipeline consistently outperforms pure vector search:
+
+1. **FTS5 keyword** — BM25-ranked full-text with injection-safe sanitization
+2. **Semantic vector** — cosine similarity on 1024-dim embeddings via numpy
+3. **MMR re-ranking** — Maximal Marginal Relevance ensures diverse results — no more five near-identical memories
+
+Every result can return a full score breakdown (vector, BM25, MMR penalty) via `memory_suggest`.
+
+### 🚫 Contradiction Detection
+
+Write a fact that conflicts with an existing one — M3 detects it automatically. The old memory is soft-deleted, a `supersedes` relationship is recorded, and the full history is preserved. No stale data, no manual cleanup.
+
+### 🕸️ Knowledge Graph
+
+Memories form a web. M3 auto-links related memories on write (cosine > 0.7) and supports 7 relationship types: `related`, `supports`, `contradicts`, `extends`, `supersedes`, `references`, `consolidates`. Traverse up to 3 hops with a single `memory_graph` call.
+
+### 🧹 Self-Maintaining
+
+- **Importance decay** — memories fade 0.5%/day after 7 days unless reinforced
+- **Auto-archival** — low-importance items (< 0.05) older than 30 days move to cold storage
+- **Per-agent retention** — set max memory count and TTL per agent
+- **Consolidation** — local LLM merges old memories into summaries when groups grow large
+- **Deduplication** — configurable cosine threshold catches near-duplicates
+
+### ⏳ Bitemporal History
+
+Track not just *when a fact was stored*, but *when it was actually true*. Query with `as_of="2026-01-15"` to see the world as your agent knew it on that date — essential for compliance and debugging.
+
+### 🤖 LLM-Powered Intelligence (Local)
+
+Any OpenAI-compatible server works (LM Studio, Ollama, vLLM, LocalAI):
+
+- **Auto-classification** — pass `type="auto"` and the LLM categorizes into 18 types
+- **Conversation summarization** — compress long threads into 3-5 key points
+- **Multi-layered consolidation** — merge related memory groups into summaries
+
+Zero API costs. Zero data exfiltration.
+
+### 🛡️ Security & Compliance
+
+| Layer | Protection |
+|-------|------------|
+| **Credentials** | AES-256 encrypted vault (PBKDF2, 600K iterations). OS keyring integration. Zero plaintext storage. |
+| **Content** | SHA-256 signing on every write. `memory_verify` detects post-write tampering. |
+| **Input** | Poisoning prevention rejects XSS, SQL injection, Python injection, and prompt injection at write boundary. |
+| **Search** | FTS5 operator sanitization prevents query injection. |
+| **Network** | Circuit breaker (3-failure threshold). Strict timeouts. Tokens never logged. |
+
+**GDPR-Ready:**
+- `gdpr_forget` — hard-deletes all data for a user (Article 17)
+- `gdpr_export` — returns all memories as portable JSON (Article 20)
+
+### 🔄 Cross-Device Sync
+
+- Bi-directional delta sync: SQLite ↔ PostgreSQL via UUID-based UPSERT
+- Crash-resistant — watermark-based tracking, at-least-once delivery
+- ChromaDB federation for distributed vector search across LAN
+- Hourly automated sync; manual sync via `chroma_sync` tool
+
+---
+
+## 25 MCP Tools
+
+| Category | Tools |
+|----------|-------|
+| **Memory Ops** | `memory_write`, `memory_search`, `memory_suggest`, `memory_get`, `memory_update`, `memory_delete`, `memory_verify` |
+| **Knowledge Graph** | `memory_link`, `memory_graph`, `memory_history` |
+| **Conversations** | `conversation_start`, `conversation_append`, `conversation_search`, `conversation_summarize` |
+| **Lifecycle** | `memory_maintenance`, `memory_dedup`, `memory_consolidate`, `memory_set_retention`, `memory_feedback` |
+| **Data Governance** | `gdpr_export`, `gdpr_forget`, `memory_export`, `memory_import` |
+| **Operations** | `memory_cost_report`, `chroma_sync` |
+
+---
+
+## Documentation
+
+| File | Purpose |
+|------|---------|
+| [CORE_FEATURES.md](./CORE_FEATURES.md) | Feature overview — start here |
+| [ARCHITECTURE.md](./ARCHITECTURE.md) | Agent instruction manual: all 25 MCP tools, protocols, usage rules |
+| [TECHNICAL_DETAILS.md](./TECHNICAL_DETAILS.md) | Deep-dive: storage internals, search pipeline, schema, sync, security |
+| [ENVIRONMENT_VARIABLES.md](./ENVIRONMENT_VARIABLES.md) | Security configuration and credential setup |
+| [CHANGELOG.md](./CHANGELOG.md) | Release history and what changed |
+| [CONTRIBUTING.md](./CONTRIBUTING.md) | How to contribute, run tests, and fix issues |
+
+---
+
+## Community
+
+Join the M3-Memory Discord server to get help, share your setup, discuss ideas, and follow development.
+
+[![Discord](https://img.shields.io/badge/Join%20Discord-M3--Memory%20Community-5865F2?logo=discord&logoColor=white&style=for-the-badge)](https://discord.gg/ZcJ3EGC99B)
+
+| Channel | Purpose |
+|---------|---------|
+| `#start-here` | New? Start here — overview & quick links |
+| `#ask-anything` | Setup help, config questions, how-tos |
+| `#bug-reports` | Report issues with steps to reproduce |
+| `#showcase` | Share your M3-Memory setups and demos |
+| `#search-quality` | Hybrid search tuning & benchmarks |
+| `#sync-federation` | Multi-device sync & ChromaDB federation |
+| `#memory-design` | Architecture discussions & research |
+
+**M3_Bot** is live in the server — mention `@M3_Bot` or use `!ask <question>` in any channel to get answers straight from the documentation.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to get started, run the test suite, and submit changes.
+
+---
+
+## Project Structure
+
+```
+bin/          Core MCP bridges, SDK, and automation scripts
+memory/       SQLite database and migration logic
+config/       Configuration templates for agents and shell
+docs/         Architecture diagrams, API reference, and OS install guides
+scripts/      Maintenance and utility scripts (fix_bugs, fix_db, fix_lint, etc.)
+logs/         Centralized audit and debug logs
+tests/        End-to-end test suite
+```
+
+---
+
+**Status:** Production Release — v2026.04 · [MIT License](LICENSE) · [Changelog](CHANGELOG.md)
+
+---
+
+[![Star History Chart](https://api.star-history.com/svg?repos=skynetcmd/m3-memory&type=Date)](https://star-history.com/#skynetcmd/m3-memory&Date)
+
+---
+
+*M3 Memory: the industrial-strength foundation for agents that remember.*