Agent Recall-代码代理的存储系统
一个工具驱动的模块化Python系统，用于持久存储有意义的代码更改。专为GitHub Copilot等AI代理设计，用于在编码会话中维护上下文。
🧱 建筑
该系统使用 以工具为中心的体系结构 使用PostgreSQL和pgvector进行高性能矢量存储和检索。每个核心功能都是按照一致的接口作为独立工具实现的。
核心组件
- 摘要ChatTool：从开发人员对话中生成有意义的摘要
- 嵌入文本工具：使用句子变换器创建向量嵌入
- 存储记忆工具：使用pgvector在PostgreSQL中持久化内存
- FetchContext工具：使用语义和元数据搜索检索相关内存
- 内存流水线工具：编排完整的内存创建过程
- PromptMemory工具：用于内存管理的交互式CLI
🚀 快速开始
先决条件
- Python 3.8+
- PostgreSQL 12+，带pgvector扩展
- OpenAI API密钥
1.安装依赖项
# Using pip
pip install -r requirements.txt
# Or using uv (recommended)
uv sync2.使用pgvector设置PostgreSQL
选项A：使用Docker（推荐）
# Run PostgreSQL with pgvector
docker run -d \
--name agent-recall-db \
-e POSTGRES_PASSWORD=your_password \
-e POSTGRES_DB=agent_recall \
-p 5432:5432 \
pgvector/pgvector:pg16选项B：本地安装
安装PostgreSQL和pgvector扩展：
# On macOS
brew install postgresql pgvector
# On Ubuntu
sudo apt install postgresql postgresql-contrib
# Install pgvector from source or package manager3.配置
复制环境模板并配置：
cp .env.example .env编辑 .env 使用您的凭据：
# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key_here
# PostgreSQL Configuration
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=agent_recall
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_postgres_password_here4.初始化数据库
python setup_database.py5.测试系统
python run_memory_pipeline.py🛠 工具使用
基本内存创建
from tools.memory_pipeline import MemoryPipelineTool
pipeline = MemoryPipelineTool()
result = pipeline.run({
"chat_log": [
"User: How do I implement JWT authentication?",
"Assistant: Here's how to create JWT tokens in Python...",
# ... more conversation
],
"metadata": {
"project": "auth_service",
"file_path": "auth/jwt_handler.py",
"tags": ["authentication", "jwt", "security"]
}
})
print(f"Memory created: {result['memory_id']}")语义搜索
from tools.fetch_context import FetchContextTool
fetch_tool = FetchContextTool()
results = fetch_tool.run({
"query": "JWT token authentication",
"limit": 5,
"similarity_threshold": 0.3
})
for memory in results["memories"]:
print(f"- {memory['heading']} (similarity: {memory['similarity_score']:.2f})")交互式记忆创建
from tools.prompt_memory import PromptMemoryTool
prompt_tool = PromptMemoryTool()
result = prompt_tool.run({
"chat_log": your_chat_messages,
"auto_confirm": False # Enables interactive editing
})📁 项目结构
agent_recall/
├── tools/ # Core tool implementations
│ ├── summarize_chat.py # GPT-4 powered summarization
│ ├── embed_text.py # Sentence transformer embeddings
│ ├── store_memory.py # PostgreSQL storage
│ ├── fetch_context.py # Semantic + metadata search
│ ├── memory_pipeline.py # End-to-end pipeline
│ └── prompt_memory.py # Interactive CLI tool
│
├── core/ # Core infrastructure
│ ├── postgres_store.py # PostgreSQL + pgvector backend
│ └── model_loader.py # AI model management
│
├── config/
│ └── settings.py # Configuration management
│
├── utils/
│ └── logger.py # Logging utilities
│
├── setup_database.py # Database initialization
├── run_memory_pipeline.py # CLI demonstration
└── requirements.txt # Python dependencies🔧 高级配置
定制型号
# Use different OpenAI model
OPENAI_MODEL=gpt-3.5-turbo
# Use different embedding model
EMBEDDING_MODEL=all-mpnet-base-v2
# Adjust embedding dimension
EMBEDDING_DIMENSION=768数据库调优
对于生产部署，请考虑以下PostgreSQL优化：
-- Increase work_mem for better vector operations
SET work_mem = '256MB';
-- Optimize for vector similarity searches
SET max_parallel_workers_per_gather = 4;🧪 测试
运行附带的CLI工具以测试功能：
python run_memory_pipeline.py这提供了一个交互式菜单，用于：
- 创建示例记忆
- 搜索现有记忆
- 交互式内存创建
- 查看统计信息
🔍 搜索功能
系统支持多种搜索模式：
- 语义搜索：使用pgvector的向量相似度
- 元数据搜索：按项目、文件、标签、日期筛选
- 混合搜索：结合两种方法以获得最佳结果
搜索示例
# Semantic search
fetch_tool.run({
"query": "error handling patterns",
"search_type": "semantic"
})
# Metadata filtering
fetch_tool.run({
"project": "web_app",
"tags": ["authentication"],
"search_type": "metadata"
})
# Hybrid (recommended)
fetch_tool.run({
"query": "database connection pooling",
"project": "backend_service",
"search_type": "hybrid"
})🚦 演出
- 矢量存储器：PostgreSQL和pgvector为相似性搜索提供了出色的性能
- 索引：用于亚线性搜索时间的自动IVFFlat索引
- 可扩展性：高效处理数千个内存
- 内存使用：针对生产部署进行了优化
🛡 安全
- 基于环境的敏感数据配置
- PostgreSQL原生安全特性
- 默认情况下没有暴露的API终结点
- 基于工具的安全代理集成架构
🤝 整合
VS代码扩展
这些工具可以集成到VS Code扩展中：
// Example VS Code extension integration
const { exec } = require('child_process');
function storeMemory(chatLog, metadata) {
const command = `python -c "
from tools.memory_pipeline import MemoryPipelineTool
import json
result = MemoryPipelineTool().run(${JSON.stringify({chat_log: chatLog, metadata})})
print(json.dumps(result))
"`;
exec(command, (error, stdout) => {
const result = JSON.parse(stdout);
console.log('Memory stored:', result.memory_id);
});
}MCP服务器
现有的MCP服务器可以扩展以使用这些工具：
from mcp.server.fastmcp import FastMCP
from tools.memory_pipeline import MemoryPipelineTool
from tools.fetch_context import FetchContextTool
mcp = FastMCP("agent-recall")
@mcp.tool()
def store_conversation(chat_log: list[str], metadata: dict = {}):
"""Store a conversation in memory."""
pipeline = MemoryPipelineTool()
return pipeline.run({"chat_log": chat_log, "metadata": metadata})
@mcp.tool()
def recall_context(query: str, limit: int = 5):
"""Recall relevant context from memory."""
fetch_tool = FetchContextTool()
return fetch_tool.run({"query": query, "limit": limit})📊 监控
检查系统统计数据：
from tools.store_memory import StoreMemoryTool
store_tool = StoreMemoryTool()
stats = store_tool.get_storage_stats()
print(f"Total memories: {stats['total_memories']}")
print(f"Projects: {list(stats['projects'].keys())}")🐛 故障排除
常见问题
- 未找到pgvector：确保已安装pgvector扩展
- 连接被拒绝：检查PostgreSQL是否正在运行以及凭据是否正确
- OpenAI API错误：验证API密钥和配额
- 内存错误：针对大型嵌入调整PostgreSQL内存设置
调试模式
启用详细日志记录：
import logging
logging.getLogger("agent_recall").setLevel(logging.DEBUG)📝 许可证
MIT许可证-有关详细信息，请参阅许可证文件。
🤲 贡献
- 分叉存储库
- 创建要素分支
- 添加新功能的测试
- 提交拉取请求
📞 支持
对于问题和疑问：
- 检查故障排除部分
- 查看PostgreSQL和pgvector文档
- 在GitHub上打开一个问题