Memory OS AI

Memory OS AI

面向 AI Agent 的自适应记忆系统 — 适用于 Claude Code、Codex CLI、VS Code Copilot、ChatGPT 和任何兼容 MCP 的客户端的通用 MCP 服务。

概念

Memory OS AI 可将本地文档（PDF、DOCX、图像、音频）转换为语义记忆，任何 AI 模型都能通过 MCP（模型上下文协议）查询这些记忆。

┌──────────────────────────────────┐
│  AI Client (any MCP-compatible)  │
│  Claude Code / Codex / Copilot   │
│  ChatGPT / custom agents         │
├──────────────────────────────────┤
│         MCP Protocol             │
│   stdio / SSE / Streamable HTTP  │
├──────────────────────────────────┤
│      Memory OS AI Server         │
│  ┌────────┐  ┌───────────────┐   │
│  │ FAISS  │  │ Chat Extractor│   │
│  │ Index  │  │ (4 sources)   │   │
│  └────────┘  └───────────────┘   │
│  ┌────────────────────────────┐  │
│  │ Cross-Project Linking      │  │
│  └────────────────────────────┘  │
└──────────────────────────────────┘

功能

• 21 个 MCP 工具，用于记忆管理、搜索、聊天持久化、项目关联和云存储
• 语义搜索，采用 FAISS + SentenceTransformers（all-MiniLM-L6-v2）
• 多格式导入：PDF、DOCX、TXT、图像（OCR）、音频（Whisper）、PPTX
• 聊天提取：自动检测 Claude、ChatGPT、Copilot 和终端历史记录
• 跨项目关联：在多个工作区之间共享记忆
• 云存储溢出：自动备份到 Google Drive、iCloud、Dropbox、OneDrive、S3、Azure、Box、B2
• 3 种传输方式：stdio（默认）、SSE（--sse）、Streamable HTTP（--http）
• MCP 资源：memory://documents/*、memory://logs/conversation、memory://linked/*
• 本地优先：默认情况下所有数据都保存在你的设备上，仅在磁盘空间不足时使用云存储

21 个 MCP 工具

工具	描述
memory_ingest	将文档文件夹编入 FAISS 索引
memory_search	对所有已编入索引的内容进行语义搜索
memory_search_occurrences	统计关键词在文档中的出现次数
memory_get_context	获取与当前任务相关的上下文
memory_list_documents	列出所有已编入索引的文档及其统计信息
memory_transcribe	转录音频文件（Whisper）
memory_status	引擎状态（索引大小、模型、设备）
memory_compact	压缩／去重 FAISS 索引
memory_chat_sync	从已配置的聊天来源同步消息
memory_chat_source_add	添加聊天来源（Claude、ChatGPT 等）
memory_chat_source_remove	移除聊天来源
memory_chat_status	所有聊天来源的状态
memory_chat_auto_detect	自动检测磁盘上的聊天工作区
memory_session_brief	会话开始时的完整记忆简报
memory_chat_save	将对话消息持久化到记忆中
memory_project_link	关联其他项目的记忆
memory_project_unlink	取消关联项目
memory_project_list	列出所有已关联的项目
memory_cloud_configure	配置用于溢出的云存储后端
memory_cloud_status	显示本地磁盘和云存储状态
memory_cloud_sync	在本地与云端之间推送、拉取或自动同步

快速开始

前提条件

• Python 3.10+
• 可选：tesseract（OCR）、ffmpeg（音频）、antiword（旧版 .doc）

# macOS
brew install tesseract ffmpeg antiword

# Ubuntu/Debian
sudo apt-get install tesseract-ocr ffmpeg antiword

安装

git clone https://github.com/romainsantoli-web/Memory-os-ai.git
cd Memory-os-ai
pip install -e ".[dev,audio]"

自动设置（推荐）

# Setup for your AI client:
memory-os-ai setup claude-code    # Claude Code
memory-os-ai setup codex          # Codex CLI
memory-os-ai setup vscode         # VS Code Copilot
memory-os-ai setup claude-desktop # Claude Desktop
memory-os-ai setup chatgpt        # ChatGPT (manual bridge)
memory-os-ai setup all            # All of the above

# Check status:
memory-os-ai setup status

手动启动

# stdio (default — Claude Code, VS Code, Codex)
memory-os-ai

# SSE transport (port 8765)
memory-os-ai --sse

# Streamable HTTP (port 8765)
memory-os-ai --http

项目结构

Memory-os-ai/
├── src/memory_os_ai/
│   ├── __init__.py          # Public API: MemoryEngine, ChatExtractor, TOOL_MODELS
│   ├── __main__.py          # python -m memory_os_ai entry point
│   ├── server.py            # MCP server — 21 tools, 3 transports, resources
│   ├── engine.py            # FAISS engine — indexing, search, compact, session brief
│   ├── cloud_storage.py     # 8 cloud backends (GDrive, iCloud, Dropbox, OneDrive, S3, Azure, Box, B2)
│   ├── storage_router.py    # Smart routing: local-first with cloud overflow
│   ├── models.py            # 21 Pydantic models + TOOL_MODELS registry
│   ├── chat_extractor.py    # 4 extractors: Claude, ChatGPT, Copilot, terminal
│   ├── instructions.py      # MEMORY_INSTRUCTIONS for AI clients
│   └── setup.py             # Auto-setup CLI for 5 AI clients
├── bridges/
│   ├── claude-code/         # CLAUDE.md with memory rules
│   ├── claude-desktop/      # config.json for Claude Desktop
│   ├── codex/               # AGENTS.md for Codex CLI
│   ├── vscode/              # mcp.json for VS Code
│   └── chatgpt/             # mcp-connection.json for ChatGPT
├── tests/                   # 410+ tests — 96% coverage
│   ├── test_memory.py       # Engine + models (60 tests)
│   ├── test_chat_extractor.py  # Chat extraction (39 tests)
│   ├── test_bridges.py      # Bridge configs (22 tests)
│   ├── test_gaps.py         # Compact, cross-project, resources (34 tests)
│   ├── test_server_dispatch.py # Server dispatch + async (61 tests)
│   ├── test_setup.py        # Setup CLI targets
│   ├── test_z_coverage_boost.py # Coverage boost (35 tests)
│   └── test_zz_full_coverage.py # Full coverage (97 tests)
├── pyproject.toml           # v3.1.0 — deps, scripts, coverage config + cloud optional deps
├── Dockerfile               # Container deployment
└── README.md

云存储（v3.1.0）

当本地磁盘空间不足时（默认剩余空间低于 500 MB），记忆数据会自动溢出到已配置的云存储后端。

支持的提供商

提供商	安装	凭据
Google Drive	pip install memory-os-ai[cloud-gdrive]	credentials_json 或 token_json + folder_id
iCloud Drive	（macOS 原生，无需额外依赖）	container 名称（默认：memory-os-ai）
Dropbox	pip install memory-os-ai[cloud-dropbox]	access_token + folder
OneDrive	（自动检测挂载） 或 Graph API	mount_path 或 access_token
Amazon S3	pip install memory-os-ai[cloud-s3]	bucket、aws_access_key_id、aws_secret_access_key
Azure Blob	pip install memory-os-ai[cloud-azure]	connection_string + container
Box	pip install memory-os-ai[cloud-box]	access_token + folder_id
Backblaze B2	pip install memory-os-ai[cloud-b2]	application_key_id、application_key、bucket_name
所有提供商	pip install memory-os-ai[cloud-all]	—

用法

# Configure via environment (auto-activates on server start)
export MEMORY_CLOUD_PROVIDER=icloud
export MEMORY_CLOUD_CONFIG='{"container": "memory-os-ai"}'
memory-os-ai

# Or configure at runtime via MCP tool:
#   memory_cloud_configure(provider="s3", credentials={"bucket": "my-bucket", ...})
#   memory_cloud_status()       → local disk + cloud usage
#   memory_cloud_sync("push")   → backup to cloud
#   memory_cloud_sync("pull")   → restore from cloud
#   memory_cloud_sync("auto")   → offload if disk low

配置

环境变量

变量	默认值	描述
MEMORY_CACHE_DIR	~/.memory-os-ai	缓存 / FAISS 索引目录
MEMORY_MODEL	all-MiniLM-L6-v2	SentenceTransformer 模型名称
MEMORY_API_KEY	（无）	SSE/HTTP 身份验证的可选 API 密钥
MEMORY_CLOUD_PROVIDER	（无）	云提供商名称（见上表）
MEMORY_CLOUD_CONFIG	（无）	JSON 凭据或 JSON 文件路径
MEMORY_DISK_THRESHOLD	524288000	云端溢出前剩余的字节数（500 MB）

开发

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
python -m pytest tests/ -v

# Run with coverage
python -m pytest tests/ --cov=memory_os_ai --cov-report=term-missing

# Coverage threshold: 80% (enforced in pyproject.toml)

许可证

GNU Lesser General Public License v3.0 (LGPL-3.0)。详情请参阅 LICENSE。

如需商业授权，请联系 [email protected]。

OpenClaw 生态系统的一部分

Memory OS AI 专为与 OpenClaw Agent 基础设施协同工作而设计：

仓库	描述
setup-vs-agent-firm	AI Agent 公司的工厂 — 28 个 SKILL.md、5 个 SOUL.md、15 个行业
mcp-openclaw-extensions	115 个 MCP 工具 — 安全审计、A2A 桥接、集群管理
Memory OS AI （本仓库）	语义记忆 + 聊天持久化 — 通用 MCP 桥接

它们共同构成完整技术栈：记忆（本仓库）→ 技能与灵魂（setup-vs-agent-firm）→ 安全与编排（mcp-openclaw-extensions）。

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

---

⚠️ AI 生成的内容 — 使用前需要人工验证。