Metadata-Version: 2.4
Name: mnemosyne-os
Version: 7.0.0
Summary: Zero-dependency AI Agent Memory Engine — L1 Lexical Cache
Home-page: https://github.com/FrankHu-HK/mnemosyne
Author: 胡景堃 (Jingkun Hu)
Author-email: hu_jingkun@qq.com
License: MIT
Keywords: ai,memory,agent,retrieval,token-optimization,zero-dependency,local-first
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: numpy
Requires-Dist: numpy; extra == "numpy"
Provides-Extra: transformers
Requires-Dist: transformers; extra == "transformers"
Provides-Extra: tiktoken
Requires-Dist: tiktoken; extra == "tiktoken"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-python
Dynamic: summary

# Mnemosyne 7.0.0 — Zero-Dependency AI Memory System

> **Mnemosyne** (慧记) — a zero-dependency, local-first AI memory system with multi-tier
> forgetting, a hash-chain ledger, a plugin SDK, a local web dashboard, and MCP support.

## Quick Start

```bash
# Zero-dependency core — no pip install required
python -c "from mnemosyne import MemoryBrain; print('Ready!')"

# Or install in development mode
pip install -e .
```

## Core Features

| Feature | Description |
|---|---|
| **Multi-tier memory** | Hot / warm / cold tiers with economic forgetting (migrate, never delete) |
| **Zero-dependency** | Core uses only the Python standard library (3.8+) |
| **Hash-chain ledger** | SHA-256 chained ledger — `verify_chain()` detects tampering |
| **Plugin SDK** | `VectorBackendPlugin` / `CryptoPlugin` / `RerankerPlugin` + official plugins |
| **MCP tools** | 13 tools over stdio JSON-RPC, with token auth and multi-tenant namespaces |
| **Web UI** | Tech-aesthetic local dashboard (no CDN) via `web_server.py` |
| **Async API** | `AsyncMemoryBrain` wrapper (asyncio) |
| **Chinese-optimized** | Bigram tokenization + FTS5 + built-in synonym dictionary |
| **Security notary** | Detects credentials, invisible Unicode, HTML injection; field-level redaction |

## Usage

### CLI

```bash
# Initialize the memory database
python mnemosyne.py --dir ./mem init

# Store a memory
python mnemosyne.py --dir ./mem retain --content "苹果公司成立于1976年"

# Search memories
python mnemosyne.py --dir ./mem recall "苹果" --k 5

# Consolidate similar memories
python mnemosyne.py --dir ./mem consolidate --dry-run

# View status / health check
python mnemosyne.py --dir ./mem status --json
python mnemosyne.py --dir ./mem doctor --json

# Knowledge graph query
python mnemosyne.py --dir ./mem graph-query "张三" --depth 2 --json

# Ledger integrity / audit
python mnemosyne.py --dir ./mem verify-integrity --json
python mnemosyne.py --dir ./mem ledger-audit <memory_id>

# Export / import
python mnemosyne.py --dir ./mem export --format json --out ./memories.json
python mnemosyne.py --dir ./mem import ./memories.json

# Migrate JSONL -> SQLite
python mnemosyne.py --dir ./mem migrate --jsonl ./mem/index.jsonl

# Start the web dashboard
python -c "from web_server import run_server; run_server(port=9090)"
```

### Python API

```python
from mnemosyne import MemoryBrain

brain = MemoryBrain("./my_memories", enable_embeddings=False)
brain.ensure_init()

# Store
brain.retain("苹果公司成立于1976年", fast=True)

# Recall
results = brain.recall("苹果", k=5)
for score, record, reasons in results:
    print(f"Score: {score:.4f} | {record['content']}")

# Token-budgeted recall
results, cost_report = brain.recall("苹果", k=5, budget_tokens=100)

# Conversation history
brain.add_conversation_turn("session-1", "user", "Tell me about Apple")
hits = brain.search_conversations("Apple", session_id="session-1")

# Context snapshot
snapshot = brain.build_context_prompt(query="Apple", max_chars=2000)
```

### Async API

```python
import asyncio
from plugins.async_wrapper import AsyncMemoryBrain

async def main():
    brain = AsyncMemoryBrain("./memories", enable_embeddings=False)
    await brain.async_retain("Hello World", fast=True)
    results = await brain.async_recall("Hello", k=5)
    print(results)
    brain.close()

asyncio.run(main())
```

### Plugins

```python
# Crypto plugin (requires cryptography; degrades gracefully otherwise)
brain = MemoryBrain("./memories", plugins=["crypto"])

# Numpy vector backend (requires numpy; optional sentence-transformers model)
brain = MemoryBrain("./memories", plugins=["numpy_vector"])

# Reranker plugin
brain = MemoryBrain("./memories", plugins=["reranker"])
```

## Project Structure

```
Mnemosyne7.0.0/
├── mnemosyne.py              # Thin facade (36 lines) re-exporting the mnemosyne package
├── mnemosyne/                # Core engine package (brain/storage/retrieval/cognitive/notary/...)
├── storage/                  # Storage backends (sqlite_backend / ledger / session_store / plugin_sdk)
├── context/                  # Context snapshots (snapshot_builder)
├── context_engine/           # Context compression engine (engine-agnostic core + Hermes adapter)
├── lexical/                  # Built-in synonym dictionary
├── profiles/                 # User profile management
├── providers/                # External provider adapter + multi-source router
├── security/                 # Contradiction detection + security report
├── session/                  # Conversation importer
├── visualization/            # Knowledge tree generator
├── plugins/                  # Extra plugins (HRR, Async)
├── mnemosyne_plugins/        # Official plugins (numpy_vector / crypto / reranker)
├── mcp_server.py             # MCP server (13 tools + auth + multi-tenant)
├── web_server.py             # Local web dashboard
├── tests/                    # unittest suite
├── benchmarks/               # Performance benchmarks
├── quality_eval/             # Retrieval quality evaluation
├── examples/                 # Runnable examples (Ollama / LangChain / MCP / CLI / embedded)
└── docs/                     # Full Chinese docs (architecture, modules, plugins, API, deployment)
```

## Testing

```bash
python -m unittest discover -s tests -v
python -m unittest tests.test_plugins -v
```

## Documentation

- `README_CN.md` — 中文说明（Chinese README）
- `docs/` — full documentation: architecture, data model, 15 module docs, 7 plugin docs, API/CLI/MCP reference, deployment, integration, commercialization
- `COMPLIANCE.md` — HIPAA / 等保 / GDPR / PIPL compliance mapping
- `comparison.md` — feature comparison with alternatives
- `CHANGELOG.md` — version history
- Reports: `quality_report.md` (retrieval quality), `benchmark_report.md` (performance), `security_report.md` (security)

## License

MIT License. See the `LICENSE` file.
