memmesh (Bvalach)

共享电子邮件

本地MCP服务器，为AI代理提供共享语义记忆。它将本地知识源索引到持久存储中，以便MCP兼容的客户端可以在会话之间搜索和重用上下文。

它的作用

SharedEm将本地知识源（笔记、代理记忆、技能、项目配置）索引到一个可搜索的存储中。然后，任何兼容MCP的代理都可以通过自然语言查询搜索所有内容。

MemMesh 2.0表面在该索引之上添加了预算感知检索。代理 应该要一辆小型车 memory_brief 首先，升级到 memory_pack 仅 当他们需要更广泛的背景和使用时 memory_entity 当他们已经知道 他们正在处理的仓库、主机、代理、工作流或其他持久对象。 经过密集的工作后，代理人可以储存一个紧凑的 turn_summary 有选择地 只宣传持久的事实 promote_memory.

┌──────────────┐        ┌──────────────┐
│  MCP Client  │        │  MCP Client  │
│      A       │        │      B       │
└──────┬───────┘        └──────┬───────┘
       │  stdio MCP            │  stdio MCP
       └──────────┬────────────┘
                  ▼
   ┌────────────────────────────┐
   │   SharedMem MCP Server     │
   │                            │
   │   ChromaDB (persistent)    │
   │   all-MiniLM-L6-v2 local  │
   │   Watchdog auto-reindex    │
   └────────────────────────────┘

工具

索引来源

配置于 config.yaml 或 config.local.yaml示例设置：

设置

先决条件

• Python 3.11+（由uv管理）
• 紫外线 包管理器

安装

cd /path/to/memmesh
uv sync
cp config.example.yaml config.yaml

第一次运行下载嵌入模型（约80MB）并索引所有源代码。后续启动使用持久的ChromaDB存储。

服务器按以下顺序解析配置：

1. SHAREDMEM_CONFIG
2. config.local.yaml
3. config.yaml
4. config.example.yaml

配置MCP客户端

对读取JSON配置的MCP客户端使用此形状：

{
  "mcpServers": {
    "sharedmem": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/memmesh", "python", "-m", "sharedmem.server"],
      "cwd": "/path/to/memmesh",
      "env": {}
    }
  }
}

对于读取TOML配置的MCP客户端：

[mcp_servers.sharedmem]
command = "uv"
args = ["run", "--directory", "/path/to/memmesh", "python", "-m", "sharedmem.server"]
cwd = "/path/to/memmesh"
startup_timeout_sec = 30
tool_timeout_sec = 60
enabled = true
env = {}

一些客户端还支持CLI注册。使用等效命令 您的客户：

mcp-client add sharedmem -- uv run --directory /path/to/memmesh python -m sharedmem.server

对于使用数组样式本地命令的客户端：

{
  "mcp": {
    "sharedmem": {
      "type": "local",
      "command": ["uv", "run", "--directory", "/path/to/memmesh", "python", "-m", "sharedmem.server"],
      "environment": {},
      "enabled": true,
      "timeout": 60000
    }
  }
}

集 SHAREDMEM_BACKEND=simple 当你想要轻量级的词法后端时 例如在受约束或沙盒运行时中。

安全与隐私

SharedEm旨在供受信任的MCP客户端在本地使用。它可以在工具结果中返回索引文件内容和绝对本地文件路径，例如 recall() 和 list_sources().

不要将不受信任的代理或远程客户端连接到对个人笔记、凭据或敏感工作文档进行索引的SharedEm实例。

将本地运行时文件置于版本控制之外。 config.yaml, config.local.yaml, .env*, data/，以及 data_runtime/ 是故意的 被忽略，因为它们可能包含私有路径、索引文本或本地状态。

用法

配置后，这些工具在任何代理会话中都会自动可用。

搜索信息

recall("how does the CP-SAT solver work")
recall("meeting notes about quarterly planning", source="notes")
recall("project setup instructions", doc_type="project_config")

存储共享内存

remember("Decision: keep weekly planning notes in the team vault", tags=["decision", "knowledge-base"])

获得紧凑的记忆简报

memory_brief("what do we know about the agent gateway", entity="agent-gateway")
memory_brief("decisions about project-alpha", budget="medium", scope_project="project-alpha")

将此用作默认检索调用。它返回简短的答案项目符号和 引用，而不是将整个块拖到上下文中。

升级到上下文包

memory_pack("architecture and deployment notes", scope_project="project-alpha", top_k=6)

仅当简报不够时才使用包。它包括精简的摘录和 结构化元数据。

打开实体配置文件

memory_entity("agent-gateway")
memory_entity("project-alpha", top_k=8)

当代理已经知道它正在处理的对象并且 不需要广泛的主题搜索。

存储结构化决策

decision_record(
  "Use the private network for remote access to the agent gateway",
  facts=["The gateway should not bind to a public interface", "Remote access uses a private network"],
  entity_refs=["agent-gateway"],
  scope_project="project-alpha",
  dedupe_key="agent_gateway_remote_access_policy"
)

当 dedupe_key 与现有的活动存储器匹配并且内容不同， SharedMem退货 conflict_detected 并写道 memory_conflict 记录 而不是默默地覆盖现有的决定。使用 conflict_policy="replace" 只有当新决定有意取代 旧的那个。

存储实体更新

entity_update(
  "project-alpha",
  "Project Alpha now uses the shared deployment workflow",
  facts=["Deployment steps are tracked as structured memory"],
  scope_project="project-alpha"
)

紧凑型转弯

turn_summary(
  "Implement budget-aware memory retrieval",
  actions=["added memory_brief", "added memory_pack"],
  result="agents can request compact memory context",
  artifacts=["src/sharedmem/server.py", "src/sharedmem/memory.py"],
  decisions=["Agents should call memory_brief before memory_pack"],
  open_questions=["whether automatic preflight context is needed"],
  next_step="observe real agent usage",
  entity_refs=["sharedmem"],
  scope_project="sharedmem"
)

有选择地推广

promote_memory(
  "c916a14cd2e2c6c4",
  "decision_record",
  summary="Agents should call memory_brief before memory_pack",
  facts=["memory_brief returns short bullets and citations"],
  entity_refs=["sharedmem"],
  scope_project="sharedmem",
  dedupe_key="default_retrieval_policy"
)

允许的促销类型有 decision_record, entity_update, preference_signal，以及 derived_artifact.

检查索引内容

list_sources()

刷新索引

reindex()                    # all sources
reindex("notes")             # specific source

建筑

src/sharedmem/
├── server.py    # MCP server (FastMCP tools, stdio transport)
├── memory.py    # MemMesh 2.0 helpers for structured memory + budget retrieval
├── store.py     # ChromaDB/simple persistent wrapper (add/query/delete)
├── indexer.py   # File scanner, markdown chunking, batch indexer
├── watcher.py   # Watchdog file watcher with debouncing
├── config.py    # YAML configuration loader
└── __main__.py  # Entry point

• 嵌入: all-MiniLM-L6-v2 通过ONNX运行时（本地，无API调用）
• 存储：ChromaDB持久模式 data/ （单个SQLite文件+HNSW索引）
• 分块：按标题拆分的Markdown文件(##/###)当大于2000个字符时
• 自动重新索引：监视器监视所有源目录；更改将取消公告（2s默认）并自动重新索引
• 前言：提取并存储为可搜索元数据

配置

复制 config.example.yaml 到 config.yaml 并对其进行编辑以添加或修改源：

sources:
  my_new_source:
    path: /path/to/directory
    patterns:
      - "**/*.md"
      - "**/*.yaml"
    exclude:
      - ".git/"
      - "node_modules/"
    type: my_type

编辑后，致电 reindex() 从任何代理或重新启动服务器。

资源足迹

• 约200MB RAM（ChromaDB+嵌入式模型）
• CPU可忽略不计，重新索引期间除外
• 磁盘： data/ 目录随着索引内容的增长而增长（9K文档约50MB）
• 单一Python进程，无Docker，无外部服务