AI导哈

AI工作流内存栈

MemoryMesh是一个本地优先的AI工作流内存栈，提供CLI工具管理Docker运行时环境，支持文档导入和AI代理内存配置。

  • by gokayokutucu
  • TypeScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 gokayokutucu/memorymesh

使用说明

内存网格

什么是MemoryMesh

MemoryMesh是用于AI工作流的本地优先内存堆栈。它附带了CLI(memorymesh)安装和管理基于Docker的运行时（MemoryMesh API、MongoDB、Neo4j、Qdrant、Ollama），以及用于设置、诊断、生命周期、GPT存档导入和文档导入的CLI流。

安装（推荐）

macOS/Linux：

curl -fsSL https://github.com/gokayokutucu/memorymesh/releases/latest/download/install.sh | bash

Windows（PowerShell）：

irm https://github.com/gokayokutucu/memorymesh/releases/latest/download/install.ps1 | iex

基于版本的安装程序行为：

  • 安装/更新 memorymesh CLI全球
  • 发射 memorymesh 安装后
  • 在支持的情况下尝试尽最大努力进行先决条件安装
  • 当无法自动安装先决条件时，打印明确的平台指南

替代手动npm安装：

npm install -g @okutucu/memorymesh
memorymesh

笔记：

  • 包名称为 @okutucu/memorymesh
  • 如果满足以下条件，首次运行将启动交互式设置 ~/.memorymesh/config.json 缺失
  • 已发布的tarball包括独立安装所需的内部运行时模块

先决条件（现阶段）：

  • Node.js 18+
  • npm in PATH
  • Docker桌面/Docker引擎

重要提示：

  • Bootstrap脚本不保证通用的自动必备安装
  • 释放资产 install.sh 和 install.ps1 由以下材料制成 scripts/bootstrap/

运行时模式

当前产品状态：

  • docker 模式：活动和支持
  • native 模式：在路线图中可见，当前已禁用/未实现

首次运行设置

当没有安装配置时，运行 memorymesh 启动安装向导流程：

  1. Docker检查(docker --version, docker info)
  2. 嵌入选择(flash 或 medium)
  3. 运行时配置持久化 ~/.memorymesh
  4. 使用Docker Compose启动堆栈
  5. Ollama准备+模型拉动
  6. 健康验证
  7. 可选的Claude Desktop MCP集成

安装程序管理的运行时主页：

~/.memorymesh/
  config.json
  runtime.env
  stack/
    docker-compose.yml

嵌入配置权限

MemoryMesh使用单个真实源来嵌入设置：

~/.memorymesh/config.json ->生成 ~/.memorymesh/runtime.env ->运行时执行

规则：

  • 通过重新运行安装程序更改嵌入模式/模型(memorymesh)
  • 高级用户可以编辑 ~/.memorymesh/config.json 直接
  • runtime.env 由自动生成 config.json
  • 如果检测到漂移，MemoryMesh将重新生成 runtime.env
  • 正常使用时，不要通过环境变量修改嵌入；这些值由MemoryMesh自动管理

高级注释：

  • 嵌入环境变量可以用于内部传输/调试，但它们不是受支持的用户配置界面

核心命令

命令 它的作用 何时使用 注意事项
memorymesh 如果需要，运行首次运行设置，否则打开运行时菜单 正常入口点 运行时操作需要工作的Docker堆栈
memorymesh doctor 运行诊断并打印PASS/WARN/FAIL 健康检查和分诊 严重故障时返回非零
memorymesh doctor --fix 尝试安全的自动修复，然后重新检查 快速修复常见问题 仅保守修复；可能仍需要手动操作
memorymesh start 启动托管Docker堆栈 启动服务 使用安装程序托管堆栈上下文
memorymesh stop 停止托管Docker堆栈 暂停本地运行时 保留堆栈工件
memorymesh reset 停止堆栈并删除容器/卷（基于标志） 清理堆栈状态 仔细确认破坏性标志
memorymesh uninstall 停止堆叠并删除 ~/.memorymesh 完全局部拆除 破坏性；使用 --yes 非交互式
memorymesh upgrade 升级脚手架命令 未来升级路径 当前阶段的占位符/脚手架
memorymesh mcp 启动MCP stdio桥 克劳德/桌面或MCP客户端集成 长时间运行的前台进程
memorymesh import:gpt --path <file-or-folder> 导入ChatGPT导出JSON/ZIP路径 将现有聊天内存带入MemoryMesh 需要运行时可用性和有效的源文件
memorymesh import:documents --path <file-or-folder> 导入本地文档（文件或文件夹） 摄取笔记、标记、CSV/JSON数据集和可搜索的项目文档 递归文件夹扫描；跳过不支持的文件

文档导入

import:documents 将本地文件导入MemoryMesh，递归扫描文件夹，解析支持的格式，在需要时对基于文本的内容进行分块，并存储源元数据以进行源感知搜索/检索。

支持的格式：

  • .txt
  • .md
  • .csv
  • .json
  • .jsonl
  • .ndjson

运行模式：

  • 交互式：运行 memorymesh，然后选择 Import documents
  • 直接命令： memorymesh import:documents --path <file-or-folder> [options]

详细的文档导入限制、策略、项目范围和检查点行为记录在 packages/cli/README.md.

Claude MCP集成

安装程序可以用以下命令修补Claude Desktop配置：

{
  "mcpServers": {
    "memorymesh": {
      "command": "memorymesh",
      "args": ["mcp"]
    }
  }
}

当前集成行为：

  • 检测macOS和Windows Claude配置路径
  • 保留不相关的配置字段
  • 安全处理丢失的配置
  • 在无效JSON上安全失败
  • 成功更新后显示重启指南

诊断

memorymesh doctor 包括以下检查：

  • Docker已安装/守护进程可访问
  • MemoryMesh堆栈服务（MemoryMesh、mongodb、neo4j、qdrant、ollama）
  • MemoryMesh HTTP运行状况
  • 安装/运行时配置有效性
  • 嵌入模型存在
  • Claude MCP配置状态

memorymesh doctor --fix 可以尝试安全维修，例如：

  • 重新启动堆栈
  • 重新拉取嵌入模型
  • 从安装配置重新生成运行时环境
  • 正在修复Claude MCP配置条目

故障排除

嵌入模型不匹配

当使用不同的嵌入维度（例如768与1024）创建现有的矢量数据时，就会发生这种情况。

决心

  1. 跑 memorymesh 重新进入设置
  2. 选择目标嵌入模式(flash 或 medium)
  3. 如果必须重建现有数据，请在提示时确认重置

不要试图通过手动导出嵌入环境变量来修复不匹配。

  1. Docker未安装
  • 安装Docker桌面/引擎，然后运行 memorymesh doctor
  1. Docker守护进程未运行
  • 启动Docker桌面/守护进程，然后运行 memorymesh start
  1. Ollama模型丢失
  • 跑 memorymesh doctor --fix 或通过堆栈路径拉取模型，然后重新运行doctor
  1. MemoryMesh健康检查失败
  • 跑 memorymesh doctor；检查堆栈状态并重新启动 memorymesh start
  1. Claude配置缺失
  • 这是非破坏性的；创建/打开Claude Desktop一次，然后重新运行集成
  1. Claude配置JSON无效
  • 手动修复JSON，然后重新运行安装程序或 memorymesh doctor --fix
  1. MCP集成在Claude中不可见
  • 确认配置包含 mcpServers.memorymesh，然后重新启动Claude Desktop
  1. Bootstrap脚本无法安装必备组件
  • 使用脚本指导输出手动安装Node/npm，然后重新运行脚本
  1. memorymesh 安装后找不到命令
  • 验证npm全局bin是否打开 PATH；重新安装 npm install -g @okutucu/memorymesh
  1. npm安装成功，但运行时堆栈不健康
  • 跑 memorymesh doctor 那么，从根本原因来看 memorymesh doctor --fix 用于安全维修和重新检查
  1. 独立的tarball/全局安装报告 EEXIST 二元冲突
  • 删除冲突的全局二进制文件/包，或使用干净的前缀重新安装，然后运行 npm install -g @okutucu/memorymesh

MemoryMesh代理使用情况

要在AI代理中启用MemoryMesh内存行为，您必须手动配置内存规则：

  1. 首选 Settings > Capabilities > Memory > Manage Memory
  2. 添加两个单独的内存条目（这将使用可用插槽中的2个内存插槽，通常为~20个）。
  3. 按原样将以下每个片段粘贴到其自己的内存条目中：
If MemoryMesh tools are available, use save_memory when: a decision is made (technical, personal, or workflow-related), something is learned or a bug is debugged, a preference or working style is clarified, or an important output is produced (code, email, document, plan, summary). Also save when the user says "remember this". Format every entry as: [INPUT] the user's request or question / [OUTPUT] the response, result, or artifact produced. No topic restriction.

If MemoryMesh tools are available, use search_memory proactively before generating a response if the topic might have relevant past context. Always search when: a new conversation starts and context feels missing, the user references something from a previous session ("last time", "we decided", "remember when"), or the current topic overlaps with decisions or outputs that may have been saved before. Trust the results — if a memory is retrieved, factor it into your answer.

开发/Monorepo注释

存储库布局：

  • apps/server：服务器包
  • packages/core：共享类型/实用程序
  • packages/runtime：共享运行时/基础架构
  • packages/cli：安装/运行时CLI

有用的开发命令：

npm run build
npm test
npm run build -w @okutucu/memorymesh
npm test -w @okutucu/memorymesh

开发人员源代码设置脚本（repo/dev工作流，而不是最终用户安装）：

./scripts/dev/install-dev.sh

发布/分发说明（当前状态）：

  • npm包目标： @okutucu/memorymesh
  • 最终用户的引导安装程序资产作为发布资产发布(install.sh, install.ps1)从 scripts/bootstrap/
  • 发布自动化是脚手架式的；将其视为不断发展，而不是完全放手

相关 MCP