使用说明

# Engram MCP

A local, sovereign, hybrid memory system for MCP-compatible agents

Semantic search • Lexical search • Persistent memory • REM-style dreaming • Secure by default

🧠 什么是Engram MCP？

Engram MCP 是一个高性能、开源的内存服务器，为AI代理提供支持 长期可搜索内存 混合检索和可选的REM风格做梦。

在神经科学领域 记忆痕迹 是大脑中记忆的物理痕迹。Engram MCP将这一概念引入人工智能系统：耐用、可审计的本地内存，可从小型项目扩展到个人知识库。

Engram是不聊天记录。它是不易失性缓存。它是一个 认知底物 对于代理商来说。

✨ 核心能力

🔍 混合搜索（语义+词汇）

向量相似性搜索 通过FAISS（可选）
词汇BM25搜索 通过SQLite FTS5
互易秩融合（RRF） 获得两全其美的排名
最大边际相关性（MMR） 为多样性重新排名

🧬 REM风格梦境（洞察力生成）

梦境循环 将共同出现的块连接成新的见解
REM触发工具 (trigger_rem_cycle)排队找一份理想的工作
启用搜索活动后自动触发做梦
见解存储为 虚拟文件 (vfs://insights/...)和其他存储器一样可搜索

🧱 持久、增量内存

块级哈希和重复数据删除
流式文件读取器（无 f.read() 在大文件上）
自动重新索引已更改的文件
嵌入缓存以避免重新嵌入相同的文本

⚡ 非阻塞架构

通过异步SQLite aiosqlite
嵌入被卸载到工作池（进程或线程）
长索引作业不阻止搜索或其他工具

🔐 默认情况下，安全性优先

明确的 路径白名单 (allowed_roots)
防止路径遍历和符号链接逃逸
DB和索引工件的仅限所有者权限

🧩 MCP-本地和生产就绪

建立在 官方MCP SDK/FastMCP
具有取消和保留功能的后台作业队列
FAISS工件的索引完整性检查（UUID+校验和）

🧬 认知智能

Engram超越静态文件来理解时间和进化:

情景记忆： 索引完整的Git历史记录。不仅搜索代码变化和 提交消息 找出过去是如何修复bug的。
免疫系统： 自动检测“Revert”提交并生成高优先级的反模式规则，以防止您重复错误。
风格模仿： 分析最近的差异，为您正在编辑的特定文件生成动态的“样式指南”，确保代理编写的代码符合您的约定。
时间耦合： 发现频繁一起更改的文件之间的隐藏依赖关系（例如。， auth.py 和 user_model.py)即使他们不互相进口。

🏗️ 架构概述

server.py                # MCP entrypoint & tool definitions
engram_mcp/
├── config.py            # Configuration + validation
├── security.py          # Path guards + project validation
├── db.py                # SQLite schema + async data access
├── parsing.py           # File discovery + supported formats
├── chunking.py          # Token-aware chunking
├── embeddings.py        # Embedding backends + worker pools
├── indexing.py          # Indexing pipeline + FAISS sharding
├── search.py            # Hybrid search, RRF, MMR
├── dreaming.py          # Dream candidate discovery
├── generation.py        # Insight generation (transformers)
├── jobs.py              # Background job manager
└── locks.py             # Project locks (read/write)

✅ 支持的内容类型

Engram使用流式阅读器和大小上限对文本和文档进行索引：

文本/代码: .txt, .md, .py, .js, .ts, .json, .yaml, .toml, .sql, .html, .css, .sh，以及更多
文件: .pdf, .docx

默认情况下忽略（可配置）： .git, node_modules、虚拟envs、IDE文件夹、构建输出、日志等。

🚀 快速开始

1.️⃣ 安装Engram MCP

pipx（建议用于CLI）

pipx install engram-mcp
engram-mcp

使用FAISS CPU启用矢量搜索（可选）：

pipx install "engram-mcp[cpu]"

启用FAISS GPU构建（可选，Linux优先支持）：

pipx install "engram-mcp[gpu]"

uv（快速、可重复的开发安装）

uv venv
uv pip install -e ".[cpu]"
uv run engram-mcp

基础安装包括 仅限FTS （没有失败，没有Numba JIT）。CPU/GPU附加功能支持矢量搜索。

2.️⃣ 配置允许的路径

Engram从 默认情况下为用户范围的位置:

操作系统	配置路径
Linux	`~/.config/engram/engram_mcp.yaml`
macOS	`~/.config/engram/engram_mcp.yaml`
窗户	`%APPDATA%\\engram\\engram_mcp.yaml`

在那里创建文件（或设置 ENGRAM_CONFIG_PATH 到文件里面该目录）。

mkdir -p ~/.config/engram
cp engram_mcp.yaml.example ~/.config/engram/engram_mcp.yaml

编辑 allowed_roots:

allowed_roots:
  - /Users/you/Documents
  - /Users/you/Projects

⚠️ 记忆痕迹 将拒绝 索引这些路径之外的任何内容。

3.️⃣ 运行服务器

engram-mcp

首次使用时下载SentenceTransformers模型，除非您预先下载（对于气隙设置，请缓存模型或点 model_name_* 到本地路径）。一旦模型缓存就绪，就不足为奇了。

Engram MCP现在可供MCP兼容的客户使用。

4.️⃣ 推荐代理系统提示

要解锁Engram的全部功能，请将此协议添加到您的AI助手的系统指令中（Cursor、Windsurf、Cline等）：

# ENGRAM AGENT PROTOCOL

1. **BOOT:** When starting a task, ALWAYS call `get_project_context(project_id)`. Read the `activeContext` to resume work exactly where you left off.
2. **STYLE:** Before writing ANY code, call `analyze_file_coding_style(file_path)`. Follow the returned conventions (naming, libraries, error handling) strictly.
3. **DEBUG:** If you see a stack trace, IMMEDIATELY call `analyze_error_stack(traceback)`. Do not manually read files until you have done this.
4. **HISTORY:** If fixing a complex bug, call `search_history(query)` to see if a similar issue was fixed in the past.
5. **SAFETY:** Before refactoring, call `analyze_temporal_couplings(project_id)` to verify implicit dependencies.

⚙️ 配置亮点

您可以通过以下方式控制Engram行为 engram_mcp.yaml:

# Storage
# db_path: ~/.local/share/engram/memory.db
# index_dir: ~/.local/share/engram/indexes

# Search
vector_backend: auto      # auto | fts | faiss_cpu | faiss_gpu
fts_top_k: 200
vector_top_k: 200
return_k: 10
enable_mmr: true
mmr_lambda: 0.7

# Indexing
chunk_size_tokens: 200
overlap_tokens: 30
max_file_size_mb: 50
ignore_patterns:
  - "**/.git/**"
  - "**/node_modules/**"

# Embeddings
embedding_backend: sentence_transformers  # sentence_transformers | ollama | openai
model_name_text: paraphrase-multilingual-MiniLM-L12-v2
model_name_code: all-MiniLM-L6-v2
ollama_model: nomic-embed-text
ollama_url: http://localhost:11434
openai_embedding_model: text-embedding-3-small

# Dreaming / REM
enable_dreaming: false
dream_model_name: gpt-4o-mini
dream_threshold: 0.8

# Performance
enable_numba: false
search_cache_ttl_s: 300
search_cache_max_items: 512
embedding_cache_ttl_s: 0
embedding_cache_max_rows: 0

环境变量

ENGRAM_CONFIG_PATH：override配置路径（必须仍位于config目录下）
ENGRAM_TOKENIZER_PATH：用于精确计数令牌的可选本地令牌化器文件
ENGRAM_GENERATION_MODEL：用于生成洞察的变压器模型（默认值： gpt2)
ENGRAM_GENERATION_DEVICE: cpu 或 cuda 用于生成（默认值： cpu)
ENGRAM_DREAM_CONTEXT_WINDOW：最大梦想提示窗口（默认值： 2048)

嵌入后端

句子转换器：本地模型（默认）通过 SentenceTransformer
奥拉玛：本地Ollama服务器 ollama_url
开放人工智能：OpenAI兼容 /embeddings 端点（set openai_api_key)

🧠 MCP工具

工具参考

工具	目的	何时使用
`index_git_history`	索引提交/差异到情节记忆中	每个项目运行一次以启用时间旅行功能
`search_history`	Git日志和提交消息的语义搜索	“上次我们是如何修复死锁的？”
`analyze_file_coding_style`	从最近的更改中提取编码模式	在编写代码以匹配仓库风格之前
`analyze_reverts`	扫描“Revert”提交和反模式	用学习填充“免疫系统”
`analyze_temporal_couplings`	发现一起更改的文件	在重构以识别隐藏的依赖关系之前
`get_project_context`	检索活动会话上下文和内存库	在新会话中调用的第一个工具
`update_memory_bank`	存储代理的学习和决策	完成任务后保留上下文
`get_codebase_overview`	快速文件统计和项目图	新存储库的代理定向工具
`find_symbol_references`	基于AST的跨文件符号查找	查找函数/类定义和用法
`analyze_error_stack`	解析Python/JS/Rust/Go堆栈跟踪	当用户粘贴错误消息时
`graph_search`	使用AST图进行符号感知代码搜索	高级语义代码导航
`query_graph_nodes`	用于代码结构分析的图遍历	了解代码关系和依赖关系

核心索引工具

`index_project`

索引目录（必须在 allowed_roots).

{
  "directory": "/Users/you/Projects/my_repo",
  "project_name": "my_repo",
  "project_type": "code",
  "wait": true
}

`update_project`

更新现有项目（使用 wait: false 排队和轮询作业状态）。

{
  "project_id": "my_repo_123",
  "wait": true
}

`search_memory`

具有可选MMR的混合语义+词汇搜索(fts_mode: strict, any，或 phrase).

{
  "query": "async sqlite performance issues",
  "project_id": "my_repo_123",
  "max_results": 10,
  "fts_mode": "strict",
  "use_mmr": true
}

`get_chunk`

按ID获取单个块。

{
  "project_id": "my_repo_123",
  "chunk_id": "...",
  "include_content": true
}

`project_info`

返回项目的元数据（块计数、嵌入模型、分片信息等）。

`project_health`

验证FAISS索引完整性、UUID和校验和。

`repair_project`

从数据库状态重建FAISS索引。

`delete_project`

删除项目和所有索引工件。

`list_projects`

返回所有索引项目。

`list_jobs` / `cancel_job`

索引、更新和梦想任务的后台作业管理。

`dream_project`

从搜索共现中排队生成洞察周期。

{
  "project_id": "my_repo_123",
  "wait": false,
  "max_pairs": 10
}

`trigger_rem_cycle`

排队一个REM风格的梦想周期（梦想创造工作的别名）。

认知智能工具

`index_git_history`

将完整的Git历史记录索引到情节内存中。 每个项目运行一次 之后 index_project 以启用时间旅行功能。

{
  "project_id": "my_repo_123",
  "since_days": 90,
  "wait": true
}

`search_history`

跨Git提交、差异和消息的语义搜索。

{
  "query": "authentication bug fix",
  "project_id": "my_repo_123",
  "max_results": 5
}

`analyze_file_coding_style`

分析最近的Git差异，以提取特定文件的编码模式。 在编写代码之前调用此命令 以符合存储库的约定。

{
  "project_id": "my_repo_123",
  "file_path": "src/auth/login.py",
  "num_commits": 10
}

退货：

命名约定
首选库
错误处理模式
代码风格指南

`analyze_reverts`

扫描“Revert”提交并生成反模式规则。填充“免疫系统”以防止重复错误。

{
  "project_id": "my_repo_123",
  "lookback_days": 180
}

`analyze_temporal_couplings`

发现经常一起更改的文件，揭示隐藏的依赖关系。

{
  "project_id": "my_repo_123",
  "min_coupling_strength": 0.6,
  "lookback_days": 90
}

`get_project_context`

检索活动会话上下文和内存库。 在每次会话开始时调用此命令 恢复工作。

{
  "project_id": "my_repo_123"
}

退货：

前几次会议的活动背景
存储的学习和决策
工作进行中状态

`update_memory_bank`

存储代理学习、决策和上下文，以供将来的会话使用。

{
  "project_id": "my_repo_123",
  "key": "refactoring_decision",
  "value": "Decided to use dependency injection for testability",
  "context": "authentication module redesign"
}

`get_codebase_overview`

快速文件统计和项目图。 调用的第一个工具 在面向代理的新会话中。

{
  "project_id": "my_repo_123"
}

`find_symbol_references`

基于AST的函数/类定义和用法查找。

{
  "project_id": "my_repo_123",
  "symbol_name": "authenticate_user",
  "symbol_type": "function"
}

`analyze_error_stack`

解析Python、JavaScript、Rust、Go和其他语言的堆栈跟踪。标识相关文件和行号。

{
  "project_id": "my_repo_123",
  "traceback": "Traceback (most recent call last):\n  File \"app.py\", line 42...",
  "language": "python"
}

`graph_search`

使用AST图进行符号感知代码搜索。在理解代码关系方面比文本搜索更强大。

{
  "project_id": "my_repo_123",
  "query": "authentication flow",
  "node_types": ["function", "class"],
  "max_results": 10
}

`query_graph_nodes`

用于代码结构分析的图遍历。探索符号、文件和模块之间的关系。

{
  "project_id": "my_repo_123",
  "start_node": "authenticate_user",
  "relationship": "calls",
  "max_depth": 3
}

🔒 安全模型

Engram MCP 将拒绝 对以下路径进行索引：

在外面 allowed_roots
通过符号链接逃离
尝试遍历(../)

这可以防止意外索引：

/
.ssh
系统文件
私有或敏感目录

存储默认值（隐私安全）

默认情况下，Engram将所有状态写入 用户范围的数据目录 （从不使用当前工作目录）：

操作系统	数据目录
Linux	`~/.local/share/engram/`
macOS	`~/Library/Application Support/engram/`
窗户	`%APPDATA%\\engram\\`

SQLite数据库和FAISS索引文件是通过以下方式创建的 仅限所有者权限以（权力）否决 db_path/index_dir 如果你想在自定义位置存储，请明确表示。

查询限制

search_memory 强制执行 max_query_chars 和 max_query_tokens 来自配置（默认值：4096个字符/256个令牌）以防止失控的嵌入成本。

⚙️ 业绩说明

嵌入

从事件循环中卸载
CPU → ProcessPoolExecutor
CUDA → 线程安全执行（无分叉危险）
支持远程嵌入后端（Ollama/OpenAI）

搜索与排名

通过FAISS进行矢量搜索（可选）
通过SQLite FTS5进行词汇搜索
RRF融合+可选MMR重新排序
在缓存中搜索重复查询

按比例编制索引

大型项目的块分片（可配置阈值）
基于IVF的FAISS指数，可配置 nlist 和 nprobe
使用UUID+校验和存储索引工件以进行完整性检查

🧪 发展

依赖锁定

此仓库使用 pip工具。使用以下内容更新锁：

pip install pip-tools
pip-compile requirements.in
pip-compile requirements-dev.in

测试

pytest

🧠 哲学

大型语言模型功能强大，但 无状态.

Engram MCP的存在是为了给代理人：

持久的记忆
他们可以重温的知识
他们可以建立的背景

这不是便利的基础设施。

这是 认知基础设施.

🛣️ 路线图

二进制矢量量化（32倍内存缩减）
Tantivy/Lucene后端选项
命名空间隔离和多租户内存
热插拔嵌入式模型
跨代理共享内存图

🤝 贡献

欢迎捐款。

如果您对以下内容感兴趣：

检索系统
代理体系结构
本地优先的人工智能
高性能Python

在这里你会有宾至如归的感觉。

📜 许可证

MIT许可证。

建立记住的代理。

使用说明

🧠 什么是Engram MCP？

✨ 核心能力

🔍 混合搜索（语义+词汇）

🧬 REM风格梦境（洞察力生成）

🧱 持久、增量内存

⚡ 非阻塞架构

🔐 默认情况下，安全性优先

🧩 MCP-本地和生产就绪

🧬 认知智能

🏗️ 架构概述

✅ 支持的内容类型

🚀 快速开始

1.️⃣ 安装Engram MCP

2.️⃣ 配置允许的路径

3.️⃣ 运行服务器

4.️⃣ 推荐代理系统提示

⚙️ 配置亮点

环境变量

嵌入后端

🧠 MCP工具

工具参考

核心索引工具

index_project

update_project

search_memory

get_chunk

project_info

project_health

repair_project

delete_project

list_projects

list_jobs / cancel_job

dream_project

trigger_rem_cycle

认知智能工具

index_git_history

search_history

analyze_file_coding_style

analyze_reverts

analyze_temporal_couplings

get_project_context

update_memory_bank

get_codebase_overview

find_symbol_references

analyze_error_stack

graph_search

query_graph_nodes