墨羽记忆 — AI Agent 安全记忆工具包

您的AI会记住每一次对话。但是——

• 是否有人在向您的记忆中写入垃圾信息？
• 昨天讨论的私密信息是否会泄露到文件中？
• 上下文窗口已满——您是否会丢失重要的内容？

MOYU是一个以安全为先的AI代理记忆层。纯Python实现，一个文件夹即可运行，即插即用。LLM增强功能默认开启；如果没有API密钥，则会静默降级，核心记忆功能仍可正常工作。

安装并开始使用：

pip install moyu-memory
moyu quickstart    # 5-minute interactive demo, zero config

使MOYU与众不同的三个特点

• 🛡️ 内置安全 — 注入检测（正则表达式 + 8类LLM防护）、个人身份信息（PII）删除、文件完整性验证、写入突发保护。安全不是附加功能，而是默认设置。
• ⏳ 生命周期自动管理 — 上下文压缩、遗忘曲线、记忆合并 — 全部自动化。当上下文填满时，不再丢失重要信息。
• 🧠 检索+自适应调优 — 语义+关键词+最近性+实体混合搜索，可配置权重。搜索反馈用于moyu tune，随着时间推移自动调整权重。

🏆 对比

总结： MOYU在安全性、离线能力、生命周期管理和可配置检索方面表现出色，而这些领域是其他替代方案很少或没有提供的。根据您的应用场景选择，而不是单纯的功能数量。

🎮 适合谁

• 您的AI代理需要具有真正安全性的持久记忆
• 经常遇到上下文限制，需要自动压缩而不丢失重要内容
• 担心PII泄露 — 不希望电话号码、ID、API密钥等出现在记忆文件中
• 希望零基础设施 — 无需Docker、数据库、注册

🔬 完整功能索引

新用户？请先阅读上面的“使MOYU与众不同的三个特点”部分，然后查看比较表。

🛡️ 防御层 (11)

🧠 内存与检索层 (8) 2 LLM增强

📊 知识层 (3) 1 LLM增强

⏳ 生命周期层 (5) 3 LLM增强

🔄 学习与反思 (2)

🔗 集成层 (6)

当开始新的对话时，读取~/.moyu/session_state.json并使用其内容从前一个会话的上下文中继续。

🛡️ 安全评估

MOYU的防御链是一个分层威慑，而不是一劳永逸的解决方案。诚实评估：

🚀 快速开始

一行安装：

pip install moyu-memory

5分钟交互式演示：

moyu quickstart
# → Auto-stores sample memories, runs injection attack tests,
# → shows defense chain in action, reports results.
# → Zero config, no API key needed

与您的代理集成：

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

或者从您的代码中：

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

复制工具包（无需pip）：

pip install -r requirements.txt

将moyu_toolkit/文件夹复制到您的项目中，然后运行python3 moyu.py。

🔌 MCP集成

MOYU可以用作模型上下文协议 (MCP) 服务器，为任何MCP兼容客户端提供横跨记忆、搜索、防御、知识图谱、知识库、生命周期、反思、学习和诊断等领域的29种工具：Hermes代理、Claude桌面版、Cherry Studio、Kimi、Cursor等。

工作原理： MOYU作为本地stdio子进程运行。客户端按需启动它；没有守护进程，也没有网络端口。

设置

pip install moyu-memory

然后在您的MCP客户端配置中添加以下内容：

{

  "mcpServers": {

    "moyu": {

      "command": "uvx",

      "args": ["--from", "moyu-memory@latest", "moyu-mcp"]

    }

  }

}

或者直接使用Python入口点：python3 -m moyu_toolkit.mcp_server

可用工具

📋 命令参考

防御与安全

moyu setup moyu verify moyu unlock moyu check moyu audit moyu init 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>

内存与检索

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

知识层

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

生命周期与上下文

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

学习与维护

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

会话与桥接

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

📚 文档

• 常见问题与反模式 — 常见陷阱及解决方案
• Python API 集成指南 — 代码示例和集成模式

📁 文件结构

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             # 5-minute interactive demo

├── moyu.py                   # CLI entry point

├── moyu_wake.py              # Startup pipeline

├── defense_toolkit/

│   ├── integrity_checker.py  # File integrity + LLM guard

│   ├── forensic_patterns.json # 516 injection detection patterns

│   └── pii_redactor.py       # PII redaction

├── tests/

│   └── test_all.py           # Automated tests

├── config.yaml               # Configuration

└── requirements.txt

📜 许可证

MIT