🧠 Semantic Memory

🎯 是什么

🚀 快速开始

安装依赖

# 克隆或进入项目目录
cd semantic-memory
# 安装核心依赖
pip install -r requirements.txt
# 仅核心功能(不含文档解析)
pip install onnxruntime faiss-cpu numpy chardet
# 完整安装(含 PDF/DOCX/XLSX 解析)
pip install PyPDF2 python-docx openpyxl python-pptx cryptography
# 可选:Web UI
pip install streamlit
# 可选:API 服务
pip install fastapi uvicorn

首次运行(自动下载模型)

from memory_manager import MemoryManager
mgr = MemoryManager() # 首次自动下载 ~100MB ONNX 模型

基础用法

from memory_manager import MemoryManager
mgr = MemoryManager()
# ── 添加记忆 ──
mem_id = mgr.add(
 text="今天和张三讨论了 AI 项目进展,效果很好。",
 tags=["工作", "AI项目"],
 importance=0.8,
 source="conversation",
)
print(f"记忆已保存: {mem_id}")
# ── 语义搜索 ──
results = mgr.search("AI 项目进展如何?", top_k=5)
for r in results:
 print(f" 相似度 {r['score']:.2%} | {r['text'][:50]}...")
# ── AI 上下文召回 ──
context = mgr.recall("张三的项目讨论", max_chars=2000)
print(context) # 可直接粘贴给大模型
# ── 知识库 ──
mgr.create_kb("我的文档库", "存放工作文档")

📖 详细用法

1. 添加记忆

# 单条记忆
mem_id = mgr.add(
 text="用户偏好在微信沟通",
 tags=["用户", "偏好"],
 importance=0.9,
 source="manual",
)
# 批量添加
mem_ids = mgr.batch_add([
 {"text": "张三负责前端", "tags": ["工作"]},
 {"text": "李四负责后端", "tags": ["工作"]},
])
# 自动分块(长文本自动切分)
mem_id = mgr.add("长文本内容..." * 100, auto_chunk=True)

2. 语义搜索

# 标准搜索
results = mgr.search(
 query="张三的联系方式",
 top_k=5, # 返回数量
 tag="工作", # 标签过滤(可选)
 min_score=0.5, # 最低相似度(可选)
 kb_name="我的文档库", # 知识库搜索(可选)
)
for r in results:
 print(f"[{r['score']:.2%}] {r['text']}")
 print(f" 标签: {r['tags']} | 重要性: {r['importance']:.1f}")

3. AI 上下文召回

# 生成 AI 可直接使用的上下文
context = mgr.recall(
 query="用户的工作偏好",
 max_chars=3000, # 最大字符数
 top_k=10,
)
# 效果示例:
# [记忆 abc123] 今天和张三讨论了AI项目进展,效果很好。
# [记忆 def456] 用户偏好通过微信沟通。

4. 知识库

# 创建知识库
mgr.create_kb("我的文档库", description="存放工作相关文档")
# 导入文档
from doc_parser import import_file_to_kb, import_directory_to_kb
# 单文件导入
import_file_to_kb("report.pdf", "我的文档库")
# 批量导入整个目录
import_directory_to_kb("./documents/", "我的文档库", tags=["归档"])
# 知识库语义搜索
results = mgr.query_kb("我的文档库", "年度报告摘要", top_k=3)

5. 交互式 CLI

python scripts/interactive.py

╔══════════════════════════════════════════════════════╗
║ Semantic Memory 交互式管理 ║
╚══════════════════════════════════════════════════════╝
 [1] 💾 添加记忆
 [2] 🔍 语义搜索
 [3] 📋 记忆列表
 [4] 🗑️ 删除记忆
 [5] 📚 知识库
 [6] ⚙️ 配置管理
 [7] 📊 统计信息
 [0] 🚪 退出
请选择操作: _

# bash
echo 'eval "$(python -m memory.completion bash)"' >> ~/.bashrc
# zsh
echo 'eval "$(python -m memory.completion zsh)"' >> ~/.zshrc
# fish
python -m memory.completion fish > ~/.config/fish/completions/memory.fish

6. Web UI

streamlit run scripts/streamlit_app.py

7. REST API 服务

python -m uvicorn scripts.api_server:app --reload --port 8765

8. Docker 部署

# 构建镜像
docker build -t semantic-memory .
# 运行(自动下载模型)
docker run -p 8765:8765 \
 -v $(pwd)/data:/app/data \
 semantic-memory
# 或使用 Docker Compose
docker compose up -d

🏗️ 系统架构

┌──────────────────────────────────────────────────────────────┐
│ Semantic Memory │
├──────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 用户界面层 │ │ API 服务层 │ │ CLI 层 │ │
│ │ │ │ │ │ │ │
│ │ Streamlit UI │ │ FastAPI │ │ interactive │ │
│ │ Streamlit │ │ REST API │ │ CLI │ │
│ │ Web App │ │ /docs │ │ shell comp. │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └────────────────────┼────────────────────┘ │
│ │ │
│ ┌─────────▼─────────┐ │
│ │ MemoryManager │ │
│ │ (统一入口) │ │
│ └─────────┬─────────┘ │
│ │ │
│ ┌────────────────────┼────────────────────┐ │
│ │ │ │ │
│ ┌──────▼──────┐ ┌────────▼────────┐ ┌────────▼────────┐ │
│ │ 记忆操作 │ │ 检索模块 │ │ 文档解析 │ │
│ │ │ │ │ │ │ │
│ │ add() │ │ search() │ │ doc_parser.py │ │
│ │ delete() │ │ recall() │ │ PDF表格提取 │ │
│ │ update() │ │ query_kb() │ │ XLSX/PPTX │ │
│ │ tag() │ │ similarity() │ │ DOCX表格 │ │
│ │ list() │ │ │ │ │ │
│ └──────┬─────┘ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │ │
│ ┌──────▼───────────────────▼────────────────────▼──────┐ │
│ │ 核心层 │ │
│ │ │ │
│ │ ┌──────────────┐ ┌────────────────┐ ┌──────────┐ │ │
│ │ │ VectorStore │ │ ONNX Embedding │ │ Config │ │ │
│ │ │ FAISS Index │ │ BGE-small-zh │ │ Logger │ │ │
│ │ └──────────────┘ └────────────────┘ └──────────┘ │ │
│ │ │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────┘

用户输入 ──→ MemoryManager.add() ──→ Text → ONNX Encoder ──→ 向量
 ↓ ↓
 [chunk text] FAISS Index
 ↓ ↓
 JSON metadata ID mapping
 ↓ ↓
 memories/ ←──────────────┘

📁 项目文件结构

semantic-memory/
├── scripts/
│ ├── __init__.py # 包入口
│ ├── core.py # ONNX Embedding 引擎
│ ├── vector_store.py # FAISS 向量存储
│ ├── memory_manager.py # 记忆管理器(核心 API)
│ ├── config.py # 配置管理
│ ├── sensitive_filter.py # 敏感信息过滤
│ ├── logging.py # 统一日志模块
│ ├── batch.py # 批量操作 API
│ ├── interactive.py # 交互式 CLI
│ ├── retry.py # 指数退避重试装饰器
│ ├── doc_parser.py # 多格式文档解析(PDF表格、XLSX、PPTX)
│ ├── streamlit_app.py # Web UI(Streamlit)
│ ├── api_server.py # FastAPI REST 服务
│ └── completion/ # Shell 自动补全
│ ├── bash_completion
│ ├── zsh_completion
│ └── fish_completion
├── tests/
│ ├── conftest.py # pytest 配置 + fixtures
│ ├── test_core.py # ONNX 引擎测试(待补充)
│ ├── test_vector_store.py
│ ├── test_memory_manager.py
│ ├── test_config.py
│ ├── test_sensitive_filter.py
│ └── test_batch.py
├── data/ # 数据目录(自动创建)
│ ├── memories/ # 记忆 JSON 文件
│ ├── kb/ # 知识库数据
│ ├── models/ # ONNX 模型缓存
│ └── logs/ # 日志文件
├── .github/
│ └── workflows/
│ └── ci.yml # GitHub Actions CI/CD
├── Dockerfile # Docker 镜像构建
├── docker-compose.yml # Docker Compose 编排
├── docker/
│ └── README.md # Docker 部署指南
├── docs/
│ └── api_examples.md # API 使用示例
├── requirements.txt # Python 依赖
├── pyproject.toml # 项目元数据 + pytest 配置
├── CONTRIBUTING.md # 贡献指南
├── LICENSE # MIT License
└── README.md # 本文件

⚙️ 配置参考

🧪 测试

# 运行全部测试
pytest tests/ -v
# 运行并生成覆盖率报告
pytest tests/ -v --cov=scripts --cov-report=html
# 仅运行单元测试(不含集成测试)
pytest tests/ -v -m "not integration"
# 单个测试文件
pytest tests/test_memory_manager.py -v

🔧 常见问题

from scripts.core import download_model
download_model() # 重新下载模型

import os
os.environ["SEMANTIC_MEMORY_DATA_DIR"] = "/path/to/data"
mgr = MemoryManager() # 模型和数据将存放在此目录

# 设置代理
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
python -c "from memory_manager import MemoryManager; MemoryManager()"

# Dockerfile.gpu(使用 onnxruntime-gpu)
FROM semantic-memory:latest
RUN pip install onnxruntime-gpu

docker run --gpus all -p 8765:8765 semantic-memory:gpu

🛠️ 扩展与定制

添加新的 Embedding 模型

from scripts.core import ONNXEmbeddingEngine
class MyEncoder(ONNXEmbeddingEngine):
 def __init__(self):
 super().__init__(model_id="your-model-id")
mgr = MemoryManager(encoder=MyEncoder())

自定义记忆过滤器

def my_filter(text: str) -> str:
 # 自定义过滤逻辑
 return text.replace("内部代号", "[已脱敏]")
from memory_manager import MemoryManager
mgr = MemoryManager(custom_filters=[my_filter])

知识库插件(文档解析器)

# 在 doc_parser.py 中注册新的解析器
PARSERS[".odt"] = _parse_odt # 添加 ODT 支持

📋 待完成功能

🤝 贡献

📄 License