moyu-memory 2.10.1

Your AI remembers every conversation. But —

• Is someone writing garbage into your memory?
• Did that private info you discussed yesterday leak into a file?
• Context window full — will you lose what matters?

MOYU is a security-first memory layer for AI Agents. Pure Python, one folder, plug and play. LLM-enhanced features are on by default; no API key? Silent degrade, core memory keeps working.

Install and go:

pip install moyu-memory
moyu quickstart    # Chinese/English launcher → 5-step interactive demo

Three things that make MOYU different

• 🛡️ Security built in — Injection detection (regex + 8-class LLM guard), PII redaction, file integrity verification, write burst protection. Security isn't an add-on, it's default.
• ⏳ Lifecycle on autopilot — Context compression, forgetting curve, memory merge — all automatic. No more losing important things when context fills up.
• 🧠 Retrieval + adaptive tuning — Semantic + keyword + recency + entity hybrid search with configurable weights. Search feedback feeds moyu tune which auto-adjusts weights over time.

🏆 Comparison

Bottom line: MOYU excels at security, offline capability, lifecycle management, and configurable retrieval — areas where alternatives offer little to none. Choose by your scenario, not by feature count.

🎮 Who is it for

• Your AI Agent needs persistent memory with real security
• Frequently hit context limits, need auto-compression without losing important content
• Worried about PII leaks — don't want phone numbers, IDs, API keys in memory files
• Want zero infrastructure — no Docker, no databases, no signups

🔬 Full Capability Index

New here? Start with the "Three things that make MOYU different" section above, then the comparison table.

🛡️ Defense Layer (11)

🧠 Memory & Retrieval Layer (8) 2 LLM-Enhanced

📊 Knowledge Layer (3) 1 LLM-Enhanced

⏳ Lifecycle Layer (5) 3 LLM-Enhanced

🔄 Learning & Reflection (2)

🔗 Integration Layer (6)

For non-Hermes agents — add this line to your Agent's system prompt to enable session continuation:

When starting a new conversation, read ~/.moyu/session_state.json and use its content to continue from the previous session's context.

🛡️ Security Assessment

MOYU's defense chain is a layered deterrent, not a silver bullet. Honest assessment:

🚀 Quick Start

One-line install:

pip install moyu-memory

5-step interactive demo with Chinese/English switcher:

moyu quickstart
# → Launcher prompts language selection, then walks through
# → 5 real-data modules: memory → defense → retrieval → stats → cleanup.
# → Zero config, no API key needed

Integrate with your Agent:

moyu inject "current conversation topic"
# → Outputs relevant memories (with context warning), ready for System Prompt injection

Or from your code:

from moyu_toolkit.moyu import inject_context
inject_context("current conversation topic")  # Auto-search, format, inject

Copy the toolkit (no pip needed):

pip install -r requirements.txt

Copy the moyu_toolkit/ folder into your project, run python3 moyu.py.

🔌 MCP Integration

MOYU can be used as a Model Context Protocol (MCP) server, exposing 29 tools across memory, search, defense, knowledge graph, knowledge base, lifecycle, reflection, learning, and diagnostics — for any MCP-compatible client: Hermes Agent, Claude Desktop, Cherry Studio, Kimi, Cursor, and more.

How it works: MOYU runs as a local stdio subprocess. Client starts it on demand; no daemon, no network port.

Setup

pip install moyu-memory

Then add this to your MCP client configuration:

{
  "mcpServers": {
    "moyu": {
      "command": "uvx",
      "args": ["--from", "moyu-memory@latest", "moyu-mcp"]
    }
  }
}

Or use the Python entry point directly: python3 -m moyu_toolkit.mcp_server

Available Tools

📋 Command Reference

Defense & Security

moyu setup moyu verify moyu unlock moyu check moyu audit moyu rules list moyu rules remove <pattern> moyu rules whitelist <pattern> moyu protect moyu benchmark moyu demo-attack moyu doctor moyu mutate moyu frequency stats moyu frequency unlock <name>

Memory & Retrieval

moyu search <query> moyu search --vote <id> good|bad moyu search --ns <ns> moyu inject <query> moyu config show moyu config set retrieval.weights.<dim> <val> moyu tune / --dry-run / --reset moyu stats moyu status moyu extract <text> moyu extract stats moyu memory detail <id> moyu memory heat-recalc

Knowledge Layer

moyu kg search <entity> moyu kg history <entity> moyu kb search <keyword>

Lifecycle & Context

moyu compress moyu context moyu forget moyu lifecycle moyu ref <name> moyu snapshot

Learning & Maintenance

moyu learn <text> moyu detect <text> moyu signals moyu quickstart moyu demo moyu reflect moyu setup agents moyu update

Session & Bridge

moyu session state moyu session prompt moyu session decision <text> moyu session pending <text> moyu session clear moyu bridge

📚 Documentation

• FAQ & Anti-Patterns — Common pitfalls and solutions
• Python API Integration Guide — Code examples and integration patterns

📁 File Structure

moyu_toolkit/
├── _llm_client.py            # Unified LLM client
├── agent_memory.py           # Vector memory engine + TEMPR retrieval
├── agent_memory_sqlite.py    # SQLite FTS5 search index
├── active_context.py         # Working memory
├── context_manager.py        # Context compression + warning + task map
├── forgetting_curve.py       # Forgetting curve + LLM review
├── memory_merge.py           # Memory merge
├── knowledge_graph.py        # Entity-relation knowledge graph
├── knowledge_base.py         # Workflow knowledge base
├── learner.py                # Learn from corrections
├── security.py               # Password + lockout
├── feedback.py               # Search feedback collection
├── tune.py                   # Adaptive weight tuning
├── quickstart.py             # Bilingual launcher + 5-step interactive demo
├── moyu.py                   # CLI entry point
├── moyu_wake.py              # Startup pipeline
├── defense_toolkit/
│   ├── integrity_checker.py  # File integrity + LLM guard
│   ├── forensic_patterns.json # 613 injection detection patterns
│   └── pii_redactor.py       # PII redaction
├── tests/
│   └── test_all.py           # Automated tests
├── config.yaml               # Configuration
└── requirements.txt

ⁿ Password verification in non-TTY environments (WebUI, Agent tools) is skipped by default. To enforce password checks everywhere, add to config.yaml:

security:
  non_tty_verify: true

Then set MOYU_SAFE_WORD environment variable for non-interactive usage.

📜 License

MIT