AI代理记忆操作系统

记忆印迹

AI代理的本地优先内存操作系统

Engram 1.0是一个用于AI代理的本地模型上下文协议（MCP）服务器和内存操作系统。它为代理提供了持久内存、引用检索、审查源代码获取、文档证据工作流、图形证据和本地运行时检查，而无需将私有项目上下文推送到托管服务。

重建的1.0运行时由以下所有者拥有 engramd：SQLite分类账、内容寻址源存储、LanceDB检索索引、Kuzu图形存储、作业、事务、快照、防火墙状态和发布/检查收据。当调用者在守护进程拥有的运行时中移动时，遗留的JSON内存和ChromaDB仍然是可读的、可重建的兼容性输入。

按稳定级别划分的当前状态 docs/ENGRAM_CURRENT_STATUS.md. 当前本地1.0版本候选检查点为 docs/ENGRAM_LOCAL_1_0_RELEASE_CANDIDATE.md.

Engram围绕一个简单的想法构建：代理应该首先检索最小的有用上下文，然后只有在证据、引用或审查状态证明其合理性时才进行扩展。

为什么选择Engram？

大多数代理内存系统以两种方式之一失败：它们在会话之间忘记了太多，或者在每个会话中加载了太多的上下文。

Engram的目标是走一条中间道路：

• 把记忆保存在你的机器上。
• 从语义上搜索，而不是依赖精确的关键字。
• 在块之前检索片段，在完整文档之前检索块。
• 给代理人收据，说明他们装载了什么以及为什么装载。
• 在成为记忆之前，将杂乱的源材料分解为可审查的证据。
• 保持持久内存可读、可编辑和可恢复。

其结果是为编码代理、研究代理、本地助理和MCP客户端提供了一个实用的会话间记忆层，这些代理需要连续性，而无需将整个知识库转储到每个提示中。

Engram提供什么

英格拉姆是第一个面对的代理人。正常路径是 memory_protocol() 为了发现， search_memories 或 context_pack 对于小上下文， query_knowledge 对于引用的定向/审查/审计数据包，以及用于写入持久状态的任何内容的显式只接受工具。

内存服务器

• Daemon拥有的内存操作系统运行时 通过 engramd，与 server_daemon_client.py 作为普通多会话代理使用的薄稳定MCP入口点。
• SQLite分类账 用于元数据、作业、事务、快照、别名、实体、概念、收据和迁移状态。
• 内容寻址源存储 用于原始、标准化和提取的证据伪影。
• LanceDB检索与Kuzu图存储 在重建的本地运行时中。
• 传统JSON/Chroma兼容性 在迁移过程中保持可读性和可恢复性。
• Markdown感知分块 尽可能保留标题和段落边界。
• 重复数据删除检查 在写入之前，明确 force=True 以（权力）否决
• 元数据筛选器 用于项目、域、标签、生命周期状态和规范内存。
• 关系链接 包括双向遍历。
• 固着表面 用于旧的或潜在的代码陈旧的记忆。

面向检索的代理

• 三层检索：搜索片段，检索块，然后仅在必要时读取完整的记忆。
• 上下文包 在一次调用中搜索、重复数据删除和检索一个有界的工作集。
• 上下文配置文件、数据包和切换 编译以任务为中心，引用工作上下文而不写入内存。
• 协议发现 因此，代理可以询问Engram如何使用内存阶梯。
• 会话引脚 其在不改变存储的元数据的情况下临时促进已知存储器。
• 代币使用估算 Engram归因于电话。
• 检索评估工具 用于检查内存阶梯是否仍按预期运行。
• 知识契约（EKC）响应 用于项目、源代码、文档、审查、审计、图形、实体、决策、实施上下文和证据包定向，并保持稳定的兼容性。

源代码和代码库工作流

• 源摄入量草案 用于成绩单、日志、交接单、设计说明和其他可审查的输入。
• 没有写预览 用于分块和本地源连接器摄入。
• 命名摄入管道 对于常见的源类型。
• 代码库映射作业 在连接的代理执行合成时收集有界存储库上下文。
• 源漂移检测 因此，除非明确强制，否则过时的映射结果将被阻止。

文档智能

• 本地PDF反汇编 无需写入活动记忆，即可清点页面、文本覆盖率、带图像的页面、页面窗口、简历标记和提取收据。
• 端到端文件接收审查包 它结合了反汇编、块预览、质量警告、工件清单、覆盖差距、策略元数据和推广指导。
• 质量报告 标记无文本页面、图像密集页面、失败页面和视觉审查需求。
• 便携式工件清单 具有页面级简历状态和内容寻址的源引用。
• 强制性OCR/视觉工作请求 对于带有图像的页面或区域，包括每个工件的覆盖要求和预期的来源合同。
• 理解数据包 对代理提供的摘要、声明、概念、实体、高价值部分、草稿内存建议以及提供的加自动生成的图覆盖率建议进行规范化。
• 显式工件存储事务 用于分类文件证据。这些存储了审查过的文档/块/覆盖率证据，而没有促进活动记忆或图形边缘。
• 查看首次促销交易 因此，只有在以下情况下，选定的文档证据才会成为持久内存或图形边缘 accept=True 并提供审阅者身份。
• 截断保护 对于大型文档：部分页面窗口报表 status: "partial", coverage_missing, resume，并且没有写布尔值，这样代理就不会把预先接受的样本误认为是完整的审查。

图表、证据和审查

• 键入图形边 支持、矛盾、精炼、引用、例子、视觉证据和相关概念。
• 审查第一批图形提案批次 库存可绘制记录，准备有界引用上下文，验证代理提供的边，并仅在以下情况下写入图边 accept=True.
• 有界图证据包 通过 query_knowledge 默认情况下，在不加载邻居内存体的情况下，显示边缘ID、证据和矛盾。
• 证据审计 关于人工制品、引文、报道收据和图表提案。
• 审查准备包 这有助于代理准备评论，而无需默默地宣传源代码或文档草稿。
• 实体配置文件、决策包、实现上下文和证据包 只有在较低级别的证据路径可用之后。

Web仪表板

• 浏览、搜索、创建、更新和删除记忆。
• 回顾陈旧的记忆和相关的记忆。
• 检查使用估计和检索评估状态。
• 检查内存操作系统运行时状态、作业、事务、审查队列、文档工件事务、升级事务、覆盖图、防火墙事件、图边、图证据收据、实体、概念、快照、技能包、EKC评估覆盖率和释放门命令。
• 监控磁盘使用情况和内存存储增长。
• 默认情况下在本地运行，在环回之外暴露时使用故障关闭令牌保护。

检索模型

Engram的核心工作流程是检索阶梯。

1. search_memories("release checklist", limit=5)
   -> scored snippets with keys and chunk IDs

2. retrieve_chunk("project_release_notes", chunk_id=2)
   -> one focused chunk

3. retrieve_memory("project_release_notes")
   -> full memory, used only when the chunk is not enough

大多数代理工作应该在步骤1或2停止。

对于紧凑的单呼叫工作集，请使用 context_pack:

context_pack(
  query="release checklist",
  project="example-project",
  max_chunks=5,
  budget_chars=6000
)

context_pack 返回选定的块、引用、省略的结果计数和预算收据，以便代理可以看到他们所花费的上下文。

对于重复的项目、来源、文件导向、审查准备， 证据审计、有界图证据或更高级别的工件族数据包 例如实体配置文件、决策包、实现上下文和证据 捆绑包，从开始 query_knowledge 如果可用。它返回键入的EKC 1.0 对兼容性的回应 engram.knowledge.*.v0 信封。使用 search_memories 和 retrieve_chunk 当你需要较低级别的证据时 除了定向、审查、审计、图形或工件系列包之外。 稳定的任务列表通过以下方式发布 memory_protocol() 作为 knowledge_contract.task_types 并且必须得到支持 core.memory_os.knowledge_eval.DEFAULT_WORKFLOW_SCENARIOS.

实践中的代理工作流

对于普通代理工作：

memory_protocol()
search_memories(query, limit=5)
retrieve_chunk(key, chunk_id)       # when the snippet is not enough
context_pack(query, max_chunks=5)   # when a compact working set is better
query_knowledge(request)            # when orientation, review, audit, or graph evidence should be cited
prepare_graph_readiness_report()    # before a bulk graphing pass
prepare_graph_proposal_batch(...)   # bounded cited context plus proposal validation
apply_graph_proposal_batch(..., accept=True, approved_by="agent-review")

对于大型源代码和文档工作：

preview_memory_chunks or prepare_source_memory
prepare_document_intake_review(source_path, max_pages=...)
prepare_visual_extraction_request / preview_visual_extraction
prepare_document_understanding_packet(agent_supplied_analysis)
prepare_document_artifact_store(review_packet)
store_document_artifact(prepared_transaction_id, accept=True, review_packet=review_packet)
prepare_document_promotion_transaction(document_draft, approved_by=...)
apply_document_promotion_transaction(transaction, accept=True)
prepare_document_ingestion_completion(document_id, ...)
complete_document_ingestion(document_id, accept=True, approved_by=...)

文档工作流程的前半部分是故意不写的。大PDF 应该在有界页面窗口中查看，并且应该保留部分数据包 直到缺失的OCR、表格、视觉和简历覆盖范围得到解决。 每个进气包包括 review_completeness这使得截断， 缺少视觉/表格/OCR证据，以及在提交简历之前明确的剩余工作 审阅者接受一个有分类账的工件。 store_document_artifact 记录分类文件证据；它不会创建 活动记忆或图形边缘。这些文章被单独评论 促销交易。文档将保持暂存状态，直到 prepare_document_ingestion_completion 报告完整的视觉/OCR/表格 覆盖率、引用的理解和审查的图表证据，以及 complete_document_ingestion 接受该结果为可用。

MCP工具表面

Engram首先公开结构化MCP工具。文本包装器仍然可供旧客户端使用，但新的集成应该更喜欢结构化工具。

代理密钥和尺寸指南：

• 避免在持久内存键中使用正斜杠字符。使用可读性 snake_case密钥，例如 engram_final_stabilization_slice_1_status_2026_05_14 因此，文件系统支持的兼容性路径和其他工具不会解释 键作为嵌套路径。
• 将直接内存写入内容保持在15K服务器端请求指导下。 对于更大的源材料，使用块预览、源摄入、文档摄入， 或工件工作流程，以便审阅者在之前看到覆盖范围和遗漏 晋升。

产品发布标识和协议标识有意分开： memory_protocol() 报告产品版本 1.0.0，协议 version: 2, 和协议 schema_version: "2026-04-27".

发现和检索

写入和元数据

组织与质量

来源、图表和评估

代码库映射

运营

兼容性文本包装

兼容性包装仍然适用于旧客户端。新的集成应该更喜欢上面的结构化工具。

安装

需求

• Python 3.10+
• Git
• 支持MCP的客户端，如Codex、Claude Code、Claude Desktop或其他MCP主机

快速开始

git clone https://github.com/ckwich/Engram.git
cd Engram
python install.py

安装程序创建虚拟环境，安装依赖项，下载本地嵌入模型，生成配置，并在以下情况下向Codex注册Engram codex CLI可用。

第一个模型下载大约是80 MB。

安装配置文件被拆分，因此普通代理会话可以保持精简：

MCP客户端设置

法典

Codex CLI将MCP注册存储在 ~/.codex/config.toml.

建议的多会话设置：运行一个本地会话 engramd 守护进程和注册 瘦守护进程客户端MCP入口点。这使得Codex会议无法导入 或拥有ChromaDB、LanceDB、Kuzu、句子转换器或文档提取 国家。

窗户：

python install.py --daemon-url http://127.0.0.1:8765 --thin-daemon-client

# Manual fallback:
codex mcp add engram `
  --env ENGRAM_DATA_DIR=C:\path\to\Engram\data `
  --env ENGRAM_DAEMON_URL=http://127.0.0.1:8765 `
  -- C:\path\to\Engram\venv\Scripts\python.exe `
  C:\path\to\Engram\server_daemon_client.py

macOS/Linux：

python install.py --daemon-url http://127.0.0.1:8765 --thin-daemon-client

# Manual fallback:
codex mcp add engram \
  --env ENGRAM_DATA_DIR=/path/to/Engram/data \
  --env ENGRAM_DAEMON_URL=http://127.0.0.1:8765 \
  -- /path/to/Engram/venv/bin/python \
  /path/to/Engram/server_daemon_client.py

直接的 server.py 注册仍然支持本地调试， 兼容性和单过程开发。只有当你 有意需要更宽的直接模式表面：

codex mcp add engram -- \
  /path/to/Engram/venv/bin/python \
  /path/to/Engram/server.py

在更改MCP注册后，打开一个新的Codex线程，或重新启动Codex。现有线程可能无法热加载新添加的MCP服务器。

Stdio客户可以在每次对话中启动一个Engram流程。Engram在每个进程中保持JSON写入可用，但一次只有一个活动进程拥有ChromaDB向量索引；辅助进程跳过矢量索引/搜索，而不是关闭MCP传输。如果在客户端崩溃或应用程序更新后积累了许多过时的Engram进程，请在诊断存储故障之前关闭旧线程或重新启动MCP主机。

克劳德代码

claude mcp add engram --scope user \
  /path/to/Engram/venv/bin/python \
  /path/to/Engram/server.py

窗户：

claude mcp add engram --scope user `
  "C:\path\to\Engram\venv\Scripts\python.exe" `
  "C:\path\to\Engram\server.py"

克劳德桌面版

将Engram添加到 claude_desktop_config.json:

{
  "mcpServers": {
    "engram": {
      "command": "/path/to/Engram/venv/bin/python",
      "args": ["/path/to/Engram/server.py"]
    }
  }
}

SSE模式

Engram默认为MCP客户端使用stdio传输。

对于SSE运输：

python server.py --transport sse --host 127.0.0.1 --port 5100

只有当您有适当的网络控制时，才能绑定到非环回主机。

本地守护程序模式

engramd.py 启动一个拥有实时Engram内存的选择加入环回守护进程 存储和矢量索引。这让MCP stdio会话充当客户端，而不是 每个代理进程都试图直接拥有嵌入式ChromaDB。

1号航站楼：

python engramd.py --host 127.0.0.1 --port 8765

默认情况下，Engram将本地数据存储在此仓库下 data/ 目录。对于 隔离守护程序烟雾测试或备用本地存储，设置 ENGRAM_DATA_DIR 开始前 engramd 或 server.py；内存JSON、ChromaDB、Chroma锁 文件和源代码引入草稿将位于该目录下。

终端2，在启动MCP服务器进程之前：

export ENGRAM_DAEMON_URL=http://127.0.0.1:8765
python server.py

PowerShell：

$env:ENGRAM_DAEMON_URL = "http://127.0.0.1:8765"
python server.py

当 ENGRAM_DAEMON_URL 指向环回URL，而守护进程尚未 可达成的， server.py 将尝试开始 engramd.py 在接受MCP之前 交通。这可以防止守护进程客户端MCP适配器成为直接ChromaDB 业主。集 ENGRAM_DAEMON_AUTOSTART=0 需要手动启动守护进程。 自动启动在以下位置写入守护进程日志 ENGRAM_DATA_DIR\operations\.

健康检查：

python engramd.py --health --host 127.0.0.1 --port 8765

冒烟测试正在运行的守护进程：

python engramd.py --smoke-test --host 127.0.0.1 --port 8765

烟雾测试检查重复风险、写入、更新元数据、模拟运行 元数据修复、搜索、读取和删除临时 _engramd_smoke_* 通过守护进程访问内存。

工艺卫生医生：

python engramd.py --doctor --host 127.0.0.1 --port 8765

医生报告守护进程健康状况以及此结账 engramd.py 和 server.py 过程。要停止过时的MCP适配器进程，请传递显式PID 根据医生的报告：

python engramd.py --stop-server-pid 12345 12346

停止命令拒绝终止 engramd.py一次CLI检查， 其他Engram签出的流程以及当前流程。

为守护进程客户端模式生成MCP客户端配置：

python server.py --generate-config --daemon-url http://127.0.0.1:8765

这发出 ENGRAM_DATA_DIR 和 ENGRAM_DAEMON_URL 在生成的MCP中 服务器环境。 ENGRAM_DATA_DIR 让Engram指向这个回购 即使Codex在您工作时启动MCP服务器，也可以存储内存 不同的项目。守护程序URL通过修剪尾部斜线进行规范化。

对于跨越多个存储库的Codex会议，更倾向于注册MCP 服务器处于守护进程客户端模式，并运行一个本地守护进程。使用 server_daemon_client.py 用于最薄的稳定存储表面，或 server.py 随着 ENGRAM_DAEMON_URL 当你需要更广泛的测试工具时 表面：

codex mcp remove engram
codex mcp add engram `
  --env ENGRAM_DATA_DIR=C:\Dev\Engram\data `
  --env ENGRAM_DAEMON_URL=http://127.0.0.1:8765 `
  -- C:\Dev\Engram\venv\Scripts\python.exe C:\Dev\Engram\server_daemon_client.py

现有的Codex会议可能仍需要新的工具发现步骤或重新启动 在他们看到Engram工具名称空间之前。重要的稳定性保证是 每个发现的Engram MCP适配器都将稳定的内存操作路由到 而不是竞争嵌入式Chroma所有权。

守护进程模式当前路由稳定的内存搜索、重复检查、块/满 读、写、源草稿准备/列出/丢弃/推广、文档 拆卸和导入审查、文档工件存储事务、文档 促销交易， query_knowledge元数据更新、元数据修复， 并通过以下方式删除 engramd重建的内存操作系统运行时也会初始化 SQLite、内容寻址源存储、LanceDB、Kuzu、作业、事务、， 快照、防火墙状态、释放门收据和本地内存操作系统 守护进程所有者下的检查器。仍支持直接进程内MCP模式 除非 ENGRAM_DAEMON_URL 已设置。托管租户授权不是 本地1.0。

Web仪表板

启动仪表板：

python webui.py

然后打开：

http://127.0.0.1:5000

仪表板首先是环回的。局部使用是有意低摩擦。 内存检查器对于正常的审查工作是只读的：它会显示守护进程 状态、内存操作系统作业、审阅准备草稿、文档工件存储 交易、促销交易、图表证据计数、EKC评估工作流程 从守护进程拥有的分类账中获取覆盖率和释放门命令。应用a 文档升级是检查员唯一的写入路径；它需要一个被接受的 文档推广交易， accept=true，非空 approved_by，以及 当暴露在环回之外时，正常的WebUI写令牌边界。

如果您将仪表板暴露在环回之外，Engram要求：

• ENGRAM_WEBUI_ACCESS_TOKEN 用于读取访问。
• ENGRAM_WEBUI_WRITE_TOKEN 用于更改请求。
• 强令牌，默认情况下最小为32个字符。
• 主机、源、请求大小、会话和浏览器安全检查。

看 docs/REMOTE_WEBUI.md 用于远程访问设置说明。

代码库映射

Engram可以为代理准备代码库映射作业。

它不会秘密地生成特定于提供者的模型来编写架构摘要。相反，它收集有界的存储库上下文，跟踪源哈希，并要求连接的代理合成和存储结果。

映射作业是数据根感知的：当 ENGRAM_DATA_DIR 已设置、准备好的作业 记录写在 ENGRAM_DATA_DIR/codebase_mapping_jobs 而不是 默认回购 data/ 文件夹。Engram自己的草图映射配置使用当前 内存操作系统域 daemon, memory_os, migration, document_intelligence, backend_status, graph, source, webui, reliability, codebase_mapping, mcp_tools，以及 legacy_adapters 所以代理商 可以映射当前的1.0架构，而不是旧的前守护进程形状。

每个准备好的域记录源哈希值并返回源漂移收据 当上下文被读取或存储时。 store_codebase_mapping_result 拒绝陈旧 准备好的上下文，除非调用者明确传递 force=True，甚至a 强制存储报告更改的、新的或丢失的源文件。中心文件 例如 server.py 和 core/memory_manager.py 当发生以下情况时，也会发出警告 大小过滤器将它们排除在外，因此审阅者知道映射上下文跳过了 重要的架构文件。

典型MCP流程：

1. read_codebase_mapping_config(project_root)
2. draft_codebase_mapping_config(project_root)
3. store_codebase_mapping_config(project_root, config)
4. preview_codebase_mapping(project_root, mode="bootstrap")
5. prepare_codebase_mapping(project_root, mode="bootstrap")
6. read_codebase_mapping_context(job_id, domain, part_index)
7. store_codebase_mapping_result(job_id, domain, content)

终端流量：

# Create .engram/config.json interactively
python engram_index.py --project /path/to/project --init

# Preview planned mapping work
python engram_index.py --project /path/to/project --mode bootstrap --dry-run

# Prepare all configured domains
python engram_index.py --project /path/to/project --mode bootstrap

# Prepare only changed domains
python engram_index.py --project /path/to/project --mode evolve

# Prepare every configured domain
python engram_index.py --project /path/to/project --mode full

示例 .engram/config.json:

{
  "project_name": "example_app",
  "domains": {
    "auth": {
      "file_globs": ["src/auth/**", "src/middleware/auth*"],
      "questions": [
        "How does authentication work?",
        "What trust boundaries matter?"
      ]
    },
    "billing": {
      "file_globs": ["src/billing/**", "src/payments/**"],
      "questions": [
        "How does the billing pipeline work?",
        "What external integration points exist?"
      ]
    }
  },
  "planning_paths": ["docs/"],
  "max_file_size_kb": 512
}

Engram跳过生成的目录、依赖文件夹、缓存、明显的秘密文件和在项目根目录外解析的符号链接。

源摄入量

对于储存前应审查的大型或嘈杂的输入，使用源摄入量：

• 会议记录
• 调试日志
• 代理人交接
• 设计注意事项
• 研究摘录
• 代码审查摘要

评审流程为：

prepare_source_memory -> inspect draft -> store_prepared_memory

在存储之前，只要源形状很重要，就可以使用无写预览工具：

• preview_memory_chunks 和 preview_source_connector 显示普通来源摄入会产生什么。
• prepare_source_memory 创建可审查的源草稿； store_prepared_memory 是明确的推广步骤。
• list_document_extractors, preview_document_source_connector, prepare_document_disassembly，以及 prepare_document_intake_review 是文件入口前门。
• prepare_document_extraction_request, prepare_document_extraction_result, preview_document_extraction, prepare_visual_extraction_request，以及 preview_visual_extraction 处理外部解析器、OCR、表格和视觉证据。
• prepare_document_understanding_packet, prepare_document_draft, prepare_document_promotion_transaction，以及 apply_document_promotion_transaction 在接受选定的内存或图形写入之前，保持代理编写的合成可审查。
• prepare_document_artifact_store 和 store_document_artifact 是明确的分类文档证据路径。它们仅在以下情况下存储工件、文档、块和覆盖率记录 accept=True 并且再次提供匹配的已审查包。
• prepare_document_ingestion_completion 和 complete_document_ingestion 是可用的文档门。分阶段的证据可以阅读和审核，但EKC文档方向在视觉/OCR/表格覆盖、理解和图形证据完成之前仍然是局部的。
• prepare_graph_readiness_report, prepare_graph_proposal_batch，以及 apply_graph_proposal_batch 是批量绘图车道。它们从可图形化的内存操作系统记录开始，为代理提供有界的引用证据以进行合成，验证候选边，并在明确接受后才写入图形/概念/实体记录。

文档拆解、提取请求/结果、理解数据包、起草提案、推广运营计划和图像/OCR观察都是证据记录，而不是可信的活动内存。视觉提取请求包括 visual_evidence_contract，每张图像的参考覆盖要求，以及 framework_strategy 因此，代理可以在可用时使用本地视觉，也可以手工操作到外部OCR/视觉框架，并通过以下方式返回观察结果 preview_visual_extraction.将原始视觉请求传递回 preview_visual_extraction 当覆盖范围很重要时；不完整视觉观察返回 status: "partial" 使用保险范围警告，而不是让草稿索赔全额保险。

文档工件存储和文档摄入审查都不会促进活动记忆或图形边缘。视觉/表格证据记录保留页码、源工件id、坐标/边界框（如果可用）、置信度和提取器id。理解数据包保持提供者中立：连接的代理提供分析，Engram将其规范化为摘要槽、声明/概念/实体候选、高值部分、低置信度警告、草稿内存建议和提供的加自动生成的图形建议。

来源摄入永远不会自动促进积极的记忆。草稿是审查记录 status: "draft", active_memory_write_performed: false，以及推广指导 对于四个有效结果：

• 将选定的耐用内容存储为Engram内存 store_prepared_memory.
• 将关系事实存储为图边 add_graph_edge.
• 在单独的应用程序中保持仅协作的工作流状态。
• 将原材料存放在Engram之外，并通过以下方式进行参考 source_uri.

被拒绝的草稿无法升级。

CLI实用程序

# MCP server, stdio transport
python server.py

# Local daemon, then opt-in MCP daemon-client mode
python engramd.py --host 127.0.0.1 --port 8765
ENGRAM_DAEMON_URL=http://127.0.0.1:8765 python server.py
python engramd.py --smoke-test --host 127.0.0.1 --port 8765

# SSE transport
python server.py --transport sse --port 5100

# Rebuild ChromaDB from JSON
python server.py --rebuild-index

# Export/import memories
python server.py --export
python server.py --import-file engram_export_YYYY-MM-DD.json

# Health and integration checks
python server.py --health
python server.py --self-test

# Agent-facing retrieval reliability harness
python server.py --agent-eval

# Generate MCP client config
python server.py --generate-config
python server.py --generate-config --daemon-url http://127.0.0.1:8765

# Memory OS migration utilities
python -m core.memory_os_migration import-legacy --legacy-dir data/memories --store-root .engram-migration/store
python -m core.memory_os_migration import-graph-edges --store-root .engram-migration/store --graph-path data/graph/edges.json
python -m core.memory_os_migration list-document-records --store-root .engram-migration/store --record-type document_draft
python -m core.memory_os_migration export-bundle --store-root .engram-migration/store --bundle .engram-migration/bundle.json
python -m core.memory_os_migration restore-bundle --store-root .engram-migration/restored --bundle .engram-migration/bundle.json
python -m core.memory_os_migration round-trip --legacy-dir data/memories --work-root .engram-migration/round-trip

# Agent-facing migration checks are also available over MCP:
# migration_dry_run, memory_os_round_trip_check, and retrieval_backend_status
# verify the legacy import and rebuilt Memory OS stores.

建筑

Engram
|-- server.py              # FastMCP server and MCP tools
|-- server_daemon_client.py # Thin MCP client that delegates to engramd only
|-- engramd.py             # Optional loopback daemon for shared local ownership
|-- webui.py               # Flask dashboard and REST API
|-- engram_index.py        # Codebase mapping CLI
|-- install.py             # Setup wizard
|-- core/
|   |-- memory_os/         # SQLite ledger, content store, LanceDB/Kuzu services
|   |-- memory_manager.py  # legacy JSON + Chroma storage, search, metadata
|   |-- embedder.py        # Local embedding model wrapper
|   |-- chunker.py         # Markdown-aware chunking
|   |-- source_intake.py   # Reviewable source drafts
|   |-- codebase_mapper.py # Agent-native codebase mapping jobs
|   |-- document_intake_workflow.py # End-to-end no-write document review packets
|   |-- document_extractors.py # Local no-write document disassembly
|   |-- document_quality.py # Document quality warnings and next-tool guidance
|   |-- document_artifacts.py # Portable artifact manifests
|   |-- document_intelligence.py # Document evidence, understanding, and promotion drafts
|   |-- graph_manager.py   # Graph policy and traversal
|   |-- graph_store.py     # Swappable graph persistence seam
|   |-- memory_os/graph_pipeline.py # Review-first graph readiness, proposal, and promotion batches
|   |-- graph_backend_status.py # No-write graph backend readiness report
|   |-- graph_backend_eval.py # No-write graph parity/cross-document readiness
|   |-- retrieval_backend_status.py # No-write backend readiness report
|   |-- retrieval_backend_eval.py # No-write vector backend comparison gates
|   |-- context_compiler.py # No-write agent context packets
|   |-- project_capsule.py # No-write project capsule drafts
|   |-- usage_meter.py     # Privacy-safe token estimates
|   |-- operation_log.py   # Job and event receipts
|   `-- reliability_harness.py
|-- data/
|   |-- memory_os/         # rebuilt ledger, objects, LanceDB, and Kuzu stores
|   |-- memories/          # legacy plain JSON memories
|   `-- chroma/            # legacy rebuildable vector index
|-- templates/             # Dashboard templates
|-- static/                # Dashboard assets
|-- tests/                 # Pytest suite
`-- docs/                  # Additional setup and operating notes

运行时依赖关系

看 requirements.txt 以及用于精确版本范围和安全级别的拆分配置文件。对于普通MCP适配器进程，瘦守护进程客户端配置文件仍然很小。

存储布局

重建的内存操作系统将操作状态存储在 data/memory_os/:

• ledger.sqlite3 用于持久元数据、收据、作业、事务、实体、概念、别名、图边镜像、快照和eval/技能包记录。
• objects/ 用于内容寻址的源工件。
• lance/ 用于可重建的检索索引。
• kuzu/ 用于可重建的图形存储。

传统兼容内存仍以普通JSON文件存储在 data/memories/.

例子：

{
  "key": "example_architecture",
  "title": "Example App Architecture Notes",
  "content": "## Overview\n...",
  "tags": ["example", "architecture", "decisions"],
  "project": "example_app",
  "domain": "architecture",
  "status": "active",
  "canonical": true,
  "created_at": "2026-03-16T14:23:00-07:00",
  "updated_at": "2026-03-16T14:23:00-07:00",
  "last_accessed": "2026-04-01T09:15:00-07:00",
  "related_to": ["example_api_contract"],
  "potentially_stale": false,
  "chunk_count": 7,
  "chars": 3200,
  "lines": 81
}

如果ChromaDB索引已损坏或删除，请运行：

python server.py --rebuild-index

设计原则

• 本地优先。 除非您公开或导出，否则内存内容将保留在您的计算机上。
• 内存操作系统优先。 Rebuild 1.0使用SQLite分类账、内容寻址源存储、LanceDB检索、Kuzu图存储和守护进程拥有的运行时。
• 记忆之前的证据。 原始和提取的来源在经过审查的持久记忆之前成为证据和草稿。
• 代币比例。 代理应首先加载最小的有用上下文。
• 人为检查噪音摄入。 大型源代码在推广前会变成草稿。
• 提供商中立。 MCP服务器和代码库映射器不需要特定的模型提供程序。
• 默认情况下可移植。 索引和图表必须从持久的分类账和内容寻址的工件中重建。

路线图

Engram 1.0是公共、通用、本地优先的内存操作系统重建：SQLite分类账、内容寻址源存储、LanceDB检索、Kuzu图推理、守护进程拥有的操作、源/文档证据、视觉/OCR覆盖率、检索收据、图关系、事务、快照、项目胶囊、技能包导出、便携式内存护照和本地内存检查器。

1.0后的工作是托管/商业打包：托管同步、租户身份验证、计费、托管MCP/neneneba API网关、托管协作桥、市场和支持操作。本地1.0不应被淡化为遗留JSON/Chroma运行时周围的就绪门。

规划文件：

• docs/ENGRAM_CURRENT_STATUS.md
• docs/ENGRAM_MEMORY_OS_REBUILD_SPEC.md
• docs/superpowers/plans/2026-05-13-engram-memory-os-rebuild-1-0-plan.md
• docs/RELEASE_GATES.md
• docs/ENGRAM_MEMORY_OS_1_0_RELEASE_CHECKLIST.md
• docs/ENGRAM_MEMORY_OS_1_0_MIGRATION_GUIDE.md
• docs/archive/legacy-local-core-1-0/README.md
• docs/ENGRAM_HOSTED_SELLABLE_CHECKLIST.md

发展

安装开发依赖项：

pip install -r requirements-dev.txt

运行测试：

python -m pytest -q

运行主要健康门：

python server.py --help
python -c "from core.memory_manager import memory_manager; print('ok')"
python engramd.py --doctor
python engramd.py --smoke-test
python server.py --health
python server.py --self-test
python server.py --agent-eval
python -m pytest tests/architecture tests/test_server_daemon_client_entrypoint.py tests/policy tests/mcp/test_no_write_tool_contracts.py tests/backend_gates -q

看 docs/RELEASE_GATES.md 用于EKC前准备就绪门和完整的1.0 释放大门。预EKC门验证瘦守护进程客户端边界， 无写审查界面、明确的写策略元数据和后端准备就绪 在新的代理合同之前，包装材料会分层放置。

贡献

欢迎问题和拉取请求。

对于代码更改，请保持JSON第一存储契约不变，并在打开PR之前运行测试套件。

许可证

麻省理工学院-见 许可证 了解详情。

建造于 CKWich.