全息上下文引擎（HCE）
用于AI助手的智能存储系统。HCE没有将整个对话历史倾倒在上下文窗口中，而是只检索最相关的记忆——比如你的大脑如何回忆相关的经历，而不是你的整个人生故事。
User Query
|
v
+---------------------------+
| HCE Middleware |
| |
| +---------+ +--------+ |
| | Entity | |Semantic| |
| | Graph | | Tree | |
| +---------+ +--------+ |
| +--------+ |
| | Focus | |
| | Buffer | |
| +--------+ |
| | |
| Context Budgeting |
| (pick best memories) |
+---------------------------+
|
v
[Context Block + Query] --> LLM --> Response
|
Store back into HCE运作原理
HCE用途 三种并行存储器结构，灵感来自人类记忆的工作原理：
| 结构 | 人类类比 | 它存储什么 | 它如何检索 |
|---|---|---|---|
| 实体图 | 联想记忆（“让我想起……”） | 概念、文件、人及其关系 | 传播激活——能量通过连接传播 |
| 语义树 | 情景记忆（过去的经历） | 每一次对话，按层次组织 | 分层相关性搜索——钻入相关分支 |
| 聚焦缓冲区 | 短期记忆（最后几分钟） | 最后N次对话转向 | 最近-最近的对话优先 |
A. 背景预算 然后，算法（贪婪背包）选择符合LLM代币预算的最佳记忆，评分如下 Utility / Token_Cost.
项目结构
hce-project/
├── hce_core.py # EntityGraph (networkx) + Spreading Activation
├── semantic_tree.py # SemanticTree + Hierarchical Relevance Search
├── entity_extractor.py # Regex/heuristic NER for text -> entities
├── project_crawler.py # Multi-language codebase indexer (Python/Java/JS/TS/Go/Rust/C/C++/Ruby)
├── hce_pipeline.py # Pipeline orchestrator + Focus Buffer + Context Budgeting
├── hce_mcp_server.py # MCP server for Claude Code integration
├── test_hce_core.py # Tests for EntityGraph + Spreading Activation
├── test_semantic_tree.py # Tests for SemanticTree + HRS
├── test_entity_extractor.py# Tests for entity extraction
├── test_project_crawler.py # Tests for project crawler
├── test_hce_pipeline.py # Tests for pipeline + buffer + budgeting
├── architecture_plan.md # Original design document
├── pyproject.toml # Dependencies and project metadata
├── CLAUDE.md # Instructions for Claude Code
└── .mcp.json # MCP server registration快速开始
# Clone and set up
git clone
cd hce-project
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
# Run tests
pytest
# Use with Claude Code (MCP integration)
# Just open the project in Claude Code — the MCP server starts automatically用法
作为Python库
from hce_pipeline import HCEPipeline
# Create a pipeline
pipeline = HCEPipeline(context_budget=4000)
# Store a conversation turn
pipeline.update(
user_query="What is spreading activation?",
ai_response="Spreading activation is an algorithm that propagates energy through a graph..."
)
# Later, retrieve relevant context for a new query
context = pipeline.retrieve_context("How does the entity graph find related concepts?")
print(context)
# >> ## Related Knowledge
# >> - [concept] spreading_activation (score: 0.85)
# >> - [concept] entity_graph (score: 0.72)
# >> ...
# Or wrap an LLM chat function
def my_chat(prompt: str) -> str:
# call your LLM here
return llm.generate(prompt)
smart_chat = pipeline.wrap_chat(my_chat)
response = smart_chat("How does the entity graph find related concepts?")
# HCE automatically enriches the prompt with context and stores the result为代码库建立索引
from project_crawler import crawl_project
# Supports Python, Java, JS/TS, Go, Rust, C/C++, Ruby
graph = crawl_project("/path/to/your/project")
print(f"Found {graph.node_count} entities and {graph.edge_count} relationships")坚持
# Save state
pipeline.save("~/.hce_state")
# Load later
pipeline = HCEPipeline.load("~/.hce_state")使用Claude Code和GitHub Copilot CLI（MCP）
HCE与任何支持 模型上下文协议，包括 克劳德代码 和 GitHub Copilot 命令行工具它跨会话提供持久内存，自动存储重要交换并检索相关上下文。
Claude代码设置
将此添加到您的项目 .mcp.json （根据您的环境调整路径）：
{
"mcpServers": {
"hce": {
"command": "/path/to/your/.venv/bin/python",
"args": ["/path/to/hce_mcp_server.py"]
}
}
}然后从以下位置添加自动行为规则 CLAUDE.md 因此，Claude Code会自动调用HCE工具。
GitHub Copilot命令行界面设置
将HCE添加到您的Copilot CLI MCP配置中 ~/.copilot/mcp-config.json:
{
"mcpServers": {
"hce": {
"type": "local",
"command": "/path/to/your/.venv/bin/python",
"args": ["/path/to/hce_mcp_server.py"]
}
}
}注： 克劳德代码读取 CLAUDE.md 用于自动行为规则（何时自动存储/检索）。Copilot CLI没有——您需要明确要求它使用HCE工具，或在Copilot的系统提示符中配置类似的规则。其他MCP兼容工具
HCE与任何MCP客户端合作，包括 VS Code （副驾驶聊天）， 光标, 帆板运动, 泽德，以及 克劳德桌面版。查看每个工具的文档，了解如何注册自定义MCP服务器。
MCP工具
| 工具 | 目的 | 调用时 |
|---|---|---|
hce_status | 显示内存统计信息（节点、边、交互、缓冲区） | 会话启动时 |
hce_retrieve_context | 搜索所有3个结构，并在代币预算内返回精心策划的上下文 | 在回答代码库/架构/历史问题之前 |
hce_store_interaction | 将对话保存为图形、树和缓冲区 | 重要交流（设计决策、错误修复、功能）后 |
hce_crawl_project | 将代码库（Python、Java、JS/TS、Go、Rust、C/C++、Ruby）索引到实体图中 | 当图为空或用户请求重新索引时 |
hce_search_graph | 通过扩散激活搜索实体图 | 查找相关代码实体或概念时 |
hce_clear_memory | 重置所有HCE状态（图、树、缓冲区） | 仅当明确请求时 |
示例：会话中发生了什么
Session Start:
Claude calls hce_status → sees 313 nodes, 7 stored interactions
Graph already populated → no need to crawl
User: "How does the authentication system work?"
Claude calls hce_retrieve_context("authentication system")
→ HCE returns: 2 graph entities (login.py, validate_token),
1 past conversation about auth design, last 2 recent turns
→ All packed within 4,000 token budget
Claude answers using that context
User: "Let's switch from JWT to session cookies"
Claude implements the change, then calls hce_store_interaction(...)
→ Decision stored in all 3 structures for future sessions
Next Session (days later):
User: "Why did we switch away from JWT?"
Claude calls hce_retrieve_context → finds the stored decision
Claude: "We switched to session cookies because..."所有数据都是本地数据
HCE将所有东西都存放在 ~/.hce_state/ 在你的机器上。没有云，没有外部API调用。请参阅 常见问题解答 了解更多详情。
常见问题解答
“我安装了HCE，但我的上下文一直在增长——它坏了吗？” 不！HCE不会缩小你当前的对话。它为LLM应用程序提供跨会话内存和智能检索。查看完整 常见问题解答 对于这个和其他常见问题。
建筑深潜
实体图(hce_core.py)
由以下内容支持的类型化属性图 networkx.MultiDiGraph.
- 节点类型： 文件、功能、概念、人物、事件
- 边缘类型： 导入、调用、关联、零件
- 检索： 传播激活——种子节点获得能量，并以衰减因子传播给邻居
[login.py] --Imports--> [user_model.py] --Part_Of--> [auth/]
| |
Calls Calls
v v
[validate()] [get_user()]语义树(semantic_tree.py)
一个Merkle/Aggregation树，其中叶子是原始对话的转折点，内部节点是摘要。
[Root: summary of everything]
/ \
[Summary: turns 1-4] [Summary: turns 5-8]
/ | | \ / | | \
T1 T2 T3 T4 T5 T6 T7 T8 <-- leaves (raw turns)分层相关性搜索（HRS）： 从根开始，计算相似度，递归到有前途的分支，修剪得分低的分支。
背景预算(hce_pipeline.py)
一种贪婪的背包算法，在代币预算内选择最佳记忆：
- 从所有三个结构中收集候选人
- 按以下方式评分
Utility / Token_Cost（效率比） - 贪婪地打包效率最高的候选人，直到预算满为止
技术栈
- Python 3.10+
- 网络x --图形数据结构
- 主控程序 --Claude代码集成的模型上下文协议
- pytest --测试
当前状态
所有4个实施阶段均已完成：
- \[x\] 第一阶段：实体图+扩散激活
- \[x\] 第二阶段：语义树+层次相关性搜索
- \[x\] 第3阶段：项目爬虫+实体提取器
- \[x\] 第四阶段：流水线中间件+MCP服务器
194项测试通过。 请参阅 建筑平面图 以了解完整的设计原理。
可扩展性
HCE非常适合单个开发人员本地使用（最多约10K个图节点，数百次交互）。如需进一步扩展，请参见 可扩展性指南 --它涵盖了当前容量、已知瓶颈和推荐的升级路径（SQLite后端、语义嵌入、增量树插入）。
已知限制
- 矢量器： 使用特征散列（词袋），而不是语义嵌入。“汽车”和“汽车”不匹配。
- 汇总人： 摘录（第一句话），而非抽象。还没有法学硕士总结。
- NER： 基于正则表达式/启发式，而不是ML。在自然文本中遗漏了许多实体。
- 非Python解析器： Java、JS/TS、Go、Rust、C/C++和Ruby使用基于正则表达式的解析（没有语义理解，可能会错过复杂的模式）。Python使用完整的AST解析。
- 平台： 文件锁定使用POSIX
fcntl.flock()--如果不进行调整，则无法在Windows上使用。
有关缩放限制和修复的完整分析，请参阅 可扩展性.md.
竞争格局
HCE的背包预算三结构并行检索在LLM内存解决方案中是独一无二的。看 COMPETITORS.md 与Mem0、Letta（MemGPT）、Zep、Cognee和SimpleMem进行详细比较，包括HCE的领先地位、需要改进的地方以及缩小差距的路线图。
许可证
麻省理工学院