memU memu-cli npm 启动器文件化个人记忆 CLIcommit / retrieve / list-files与底层实现剖析【免费下载链接】memUPersonal memory across agents项目地址: https://gitcode.com/GitHub_Trending/mem/memU本文以 npm/README.md 为主体系统讲解 memU 项目在 npm 上的发布形态memu-cli一个只有几 kB、零依赖的 Node 启动器负责把commit持久化记忆、retrieve纯 embedding 检索、list-files列出全部记忆/技能文件三个命令委派给 PyPI 上的 Python 引擎。读完后你可以独立完成本地 SQLite 与 MemU Cloud 两种模式下的安装、配置与调用并理解启动器回退策略、环境变量解析顺序与云端客户端的底层行为。memu-cli 的定位Python 引擎之上的薄启动层memU 是一个个人记忆即文件personal memory as files的项目由外部 Agent 准备好记忆与技能文档memU 负责持久化这些文档并在后续对话中用 embedding 相似度检索出紧凑、排序好的上下文替代把每个 prompt 重新塞满的粗放做法。一个关键设计约束是embedding-only——memU 内部不发生任何 LLM 调用因此检索路径快速且无额外推理成本见 npm/README.md 开头说明与 src/memu/cli.py 的模块注释。项目有两种安装面形态包说明npm 包memu-clinpm/package.json薄启动器bin 入口 npm/bin/memu.js几 kB、无第三方依赖要求 Node 18PyPI 包memu-clipyproject.tomlmemU 引擎本体提供memu可执行入口与MemoryService库 API预构建 wheel 覆盖 Linuxx86_64/aarch64、macOSIntel/Apple Silicon与 Windowsnpm 与 PyPI 两个包同名但职责不同当前仓库中 npm 侧版本为0.2.0PyPI 侧引擎版本为0.11.0-beta.3requires-python 3.11支持 3.11/3.12/3.13。启动器把如何找到 Python 运行时这一麻烦封装掉用户只需npx memu-cli command。快速开始唯一前置依赖是 uv官方快速开始要求只预装 uv ——它会同时拉取 Python 3.13 运行时和 memU 引擎本身无需其他预装curl -LsSf https://astral.sh/uv/install.sh | sh # macOS / Linux # Windows: powershell -c irm https://astral.sh/uv/install.ps1 | iex然后设置 embedding 服务的密钥并执行三个基本命令export OPENAI_API_KEYsk-... # 持久化准备好的记忆{recall_files: [...], resource: [...]} npx memu-cli commit results.json # 列出所有已存储的记忆/技能文件 npx memu-cli list-files # 单发 embedding 检索 —— 无 LLM、速度快 npx memu-cli retrieve deploy checklist默认情况下状态持久化在本地 SQLite 数据库./data/memu.sqlite3。三个核心命令commit payload.json持久化外部准备好的记忆commit接收一个 JSON 文件-表示从 stdin 读取把外部流程例如 Agent 会话准备好的召回文件recall files和工作区资源resources写入存储。从 src/memu/cli.py 的_cmd_commit可以看到payload 支持三个可选顶层字段recall_files召回文件数组记忆与技能两个 track 的文件resource工作区资源数组user用户/Agent 作用域字段。提交成功后默认输出形如committed N recall file(s) and M resource(s)并逐行列出track/name加--json则输出原始 JSON 响应。文件不存在时命令返回退出码 2 并打印error: no such file: ...。retrieve query别名search零 LLM 调用的单发检索retrieve对记忆分段、文件与资源按 embedding 相似度排序并返回全程不调用 LLM。命令实现见 src/memu/cli.py构建后端后直接调用progressive_retrieve(query)打印 JSON 结果。该协议在 src/memu/agentic_backend.py 中以 Protocol 形式定义本地MemoryService与云端CloudMemoryClient都满足同一接口保证两条执行路径行为一致。list-files跨 track 列出全部召回文件list-files会遍历 memory 与 skill 两个 track 的全部召回文件。从 src/memu/cli.py 的实现可以看出它并非一次拉取而是跟随next_cursor逐页请求list_all_recall_files对应 docs/adr/0014-paginated-list-all-recall-files.md 的分页设计拼齐全量后再打印N recall file(s)与每行- {track}/{name}: {description}加--json输出完整{recall_files: [...]}。公共选项与环境变量映射每个子命令都挂载了同一组本地服务选项在 cloud 模式下被忽略来自 src/memu/cli.py 的_add_common_options。每个命令行参数都有对应的MEMU_*环境变量CI 或 Agent 只需配置一次环境即可选项环境变量默认值说明--providerMEMU_EMBED_PROVIDERopenaiembedding 提供商标识如openai、jina、voyage--embed-modelMEMU_EMBED_MODEL取 provider 默认模型覆盖 embedding 模型--base-urlMEMU_BASE_URL取 provider 端点API base URL 覆盖--api-keyMEMU_API_KEY取 provider 的密钥变量如OPENAI_API_KEYAPI key 值或环境变量名--dbMEMU_DB./data/memu.sqlite3SQLite 文件路径、postgres://DSN 或:memory:--json—关打印原始 JSON 响应关于--dbsrc/memu/env.py 的database_config说明了取值范围裸 SQLite 路径、完整 SQLAlchemy URLsqlite:///…、postgres://…或内存哨兵值:memory:/inmemory。裸路径会自动创建父目录。本地与云端双模式本地模式默认不设任何记忆模式变量时引擎在本地构建MemoryServiceembedding 在客户端计算元数据与向量写入MEMU_DB指定的 SQLite或 Postgres DSN。这里有一个容易踩坑的点src/memu/env.py 的模块注释解释得很清楚写入侧record与检索侧inject必须使用同一个 DSN 和同一个 embedding provider否则查询向量与被比较向量处于不同的向量空间检索会静默返回空结果。因此配置解析遵循三级顺序进程环境变量MEMU_DB… memu retrieve …可一次性覆盖无需改文件~/.memu/config.env安装时写入的 dotenv可用MEMU_CONFIG_ENV改路径——定时任务没有可靠的工作目录也不继承交互式 shell绝对路径下的文件是唯一稳健的载体代码内默认值。Cloud 模式设置两个变量即可让完全相同的命令改走 MemU Cloudexport MEMU_MEMORY_MODEcloud export MEMU_CLOUD_API_KEYmemu-api-keyAPI key 需在 memu.so 注册后获取生产 API base 默认为https://api.memu.so/api/v4/memory/可用MEMU_CLOUD_BASE_URL覆盖以对接兼容部署见 src/memu/cloud.py 的DEFAULT_CLOUD_BASE_URL与 src/memu/env.py本地 embedding 配置MEMU_EMBED_PROVIDER、MEMU_EMBED_MODEL、MEMU_DB等与云端凭证完全独立、互不复用cloud 模式下本地专用选项被忽略见build_agentic_memory_backend_from_envsrc/memu/env.py能力边界Cloud 目前持久化 memory 与 skill 召回文件但不持久化提交的工作区资源MEMU_MEMORY_MODE只接受local/cloud其他取值直接抛ConfigErrorcloud 模式下缺少MEMU_CLOUD_API_KEY同样显式报错而不是猜测。从 src/memu/cloud.py 的CloudMemoryClient还可以看到几个实现细节对排障很有用三个操作list_all_recall_files/progressive_retrieve/commit_results分别映射为GET带cursor分页参数、POST search、POSTpayload 为{user, recall_files, resource}鉴权头为Authorization: Bearer key默认 3 次尝试、超时 30s连接 5s对可重试状态码做指数退避重试max_attempts最小为 1作用域where只支持user_id与agent_id的精确过滤缺省值为defaultuser字段仅支持user_id、agent_id、user_name、agent_name其他字段会抛出配置错误错误按状态码分类401 认证失败、403 授权失败、400/409/422 请求被拒、429 限流其余归为服务错误支持MEMU_HTTP_PROXY显式代理未设置时默认绕过代理的 mount 规则~/.memu/config.env中的NO_PROXY/no_proxy会被透传进进程环境src/memu/env.py。embedding 配置memU 唯一的模型能力因为 memU 内部没有 LLMMEMU_EMBED_PROVIDER命名的就是唯一剩下的模型能力。src/memu/embedding/defaults.py 是 provider 知识的单一来源内置五个后端均在 src/memu/embedding/backends/ 下有真实实现provider默认模型端点密钥环境变量openaitext-embedding-3-small字段默认值OPENAI_API_KEYjinajina-embeddings-v3https://api.jina.ai/v1JINA_API_KEYvoyagevoyage-3.5https://api.voyageai.com/v1VOYAGE_API_KEYdoubaodoubao-embedding-large-text-250515https://ark.cn-beijing.volces.comARK_API_KEYopenrouteropenai/text-embedding-3-smallhttps://openrouter.aiOPENROUTER_API_KEYprovider 的解析还带一个兼容性细节MEMU_LLM_PROVIDER作为MEMU_EMBED_PROVIDER的后备被读取让旧版~/.memu/config.env继续可用见 src/memu/env.py。npm shim 如何拉起 Python四级回退策略npm/package.json 声明了bin入口memu - bin/memu.js且files只包含bin目录——整个 npm 包就是 npm/bin/memu.js 这一个几十行的 Node 脚本。它按优先级依次探测并委派$MEMU_PYTHON -m memu——显式解释器覆盖适合自定义虚拟环境uvx --from memu-cli memu——无需安装、由 uv 缓存官方推荐路径pipx run --spec memu-cli memu——无需安装、由 pipx 缓存python3 -m memu——要求已执行pip install memu-cli。探测逻辑本身也很直接has(cmd)用spawnSync(cmd, [--version])判断可执行文件存在且退出码为 0第 4 级还会先python3 -c import memu确认包已安装才使用。若四级全部落空脚本打印安装指引安装 uv / pipx / 或 pip 安装或用MEMU_PYTHON指向已装 memU 的解释器并以退出码 1 结束。子进程的退出码会原样透传给用户stdio 直接继承。已经使用 Python 的用户可以完全跳过 npmnpm 层只是分发糖。若环境中已有 Python可以uvx --from memu-cli memu --help # 无需安装uv 缓存 # 或 pip install memu-cli同一个 PyPI 包还携带库 APIMemoryService、Postgres 后端——一次安装同时覆盖 CLI、宿主适配器与库调用。从 pyproject.toml 的[project.scripts]可以看到完整的可执行入口面除核心memu算法面外还有memu-codex、memu-claude-code、memu-cursor、memu-openclaw、memu-hermes、memu-workbuddy、memu-cola、memu-pi等宿主适配器二进制以及用于任意 Agent 的memu-agent通用适配器ADR 0008/0009/0010/0011 描述的设计。核心memu二进制的retrieve/list-files/commit用法与npx memu-cli完全一致。小结npx memu-cli的价值在于把Python 引擎 运行时管理封装成一条 npx 命令npm 启动器npm/bin/memu.js负责按MEMU_PYTHON→uvx→pipx→python3的顺序找到可用运行时PyPI 引擎入口memu.cli:main负责实际的 commit/retrieve/list-files 语义MEMU_*环境变量统一了本地与云端两条路径的配置面。对 CI 与 Agent 集成而言配置一次环境、只传命令正是这套设计的直接收益而 embedding-only、零 LLM 调用的检索路径则是它可以在低延迟、低成本前提下被高频调用的原因。项目采用 Apache-2.0 许可见 LICENSE.txt。【免费下载链接】memUPersonal memory across agents项目地址: https://gitcode.com/GitHub_Trending/mem/memU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
memU memu-cli npm 启动器：文件化个人记忆 CLI（commit / retrieve / list-files）与底层实现剖析
memU memu-cli npm 启动器文件化个人记忆 CLIcommit / retrieve / list-files与底层实现剖析【免费下载链接】memUPersonal memory across agents项目地址: https://gitcode.com/GitHub_Trending/mem/memU本文以 npm/README.md 为主体系统讲解 memU 项目在 npm 上的发布形态memu-cli一个只有几 kB、零依赖的 Node 启动器负责把commit持久化记忆、retrieve纯 embedding 检索、list-files列出全部记忆/技能文件三个命令委派给 PyPI 上的 Python 引擎。读完后你可以独立完成本地 SQLite 与 MemU Cloud 两种模式下的安装、配置与调用并理解启动器回退策略、环境变量解析顺序与云端客户端的底层行为。memu-cli 的定位Python 引擎之上的薄启动层memU 是一个个人记忆即文件personal memory as files的项目由外部 Agent 准备好记忆与技能文档memU 负责持久化这些文档并在后续对话中用 embedding 相似度检索出紧凑、排序好的上下文替代把每个 prompt 重新塞满的粗放做法。一个关键设计约束是embedding-only——memU 内部不发生任何 LLM 调用因此检索路径快速且无额外推理成本见 npm/README.md 开头说明与 src/memu/cli.py 的模块注释。项目有两种安装面形态包说明npm 包memu-clinpm/package.json薄启动器bin 入口 npm/bin/memu.js几 kB、无第三方依赖要求 Node 18PyPI 包memu-clipyproject.tomlmemU 引擎本体提供memu可执行入口与MemoryService库 API预构建 wheel 覆盖 Linuxx86_64/aarch64、macOSIntel/Apple Silicon与 Windowsnpm 与 PyPI 两个包同名但职责不同当前仓库中 npm 侧版本为0.2.0PyPI 侧引擎版本为0.11.0-beta.3requires-python 3.11支持 3.11/3.12/3.13。启动器把如何找到 Python 运行时这一麻烦封装掉用户只需npx memu-cli command。快速开始唯一前置依赖是 uv官方快速开始要求只预装 uv ——它会同时拉取 Python 3.13 运行时和 memU 引擎本身无需其他预装curl -LsSf https://astral.sh/uv/install.sh | sh # macOS / Linux # Windows: powershell -c irm https://astral.sh/uv/install.ps1 | iex然后设置 embedding 服务的密钥并执行三个基本命令export OPENAI_API_KEYsk-... # 持久化准备好的记忆{recall_files: [...], resource: [...]} npx memu-cli commit results.json # 列出所有已存储的记忆/技能文件 npx memu-cli list-files # 单发 embedding 检索 —— 无 LLM、速度快 npx memu-cli retrieve deploy checklist默认情况下状态持久化在本地 SQLite 数据库./data/memu.sqlite3。三个核心命令commit payload.json持久化外部准备好的记忆commit接收一个 JSON 文件-表示从 stdin 读取把外部流程例如 Agent 会话准备好的召回文件recall files和工作区资源resources写入存储。从 src/memu/cli.py 的_cmd_commit可以看到payload 支持三个可选顶层字段recall_files召回文件数组记忆与技能两个 track 的文件resource工作区资源数组user用户/Agent 作用域字段。提交成功后默认输出形如committed N recall file(s) and M resource(s)并逐行列出track/name加--json则输出原始 JSON 响应。文件不存在时命令返回退出码 2 并打印error: no such file: ...。retrieve query别名search零 LLM 调用的单发检索retrieve对记忆分段、文件与资源按 embedding 相似度排序并返回全程不调用 LLM。命令实现见 src/memu/cli.py构建后端后直接调用progressive_retrieve(query)打印 JSON 结果。该协议在 src/memu/agentic_backend.py 中以 Protocol 形式定义本地MemoryService与云端CloudMemoryClient都满足同一接口保证两条执行路径行为一致。list-files跨 track 列出全部召回文件list-files会遍历 memory 与 skill 两个 track 的全部召回文件。从 src/memu/cli.py 的实现可以看出它并非一次拉取而是跟随next_cursor逐页请求list_all_recall_files对应 docs/adr/0014-paginated-list-all-recall-files.md 的分页设计拼齐全量后再打印N recall file(s)与每行- {track}/{name}: {description}加--json输出完整{recall_files: [...]}。公共选项与环境变量映射每个子命令都挂载了同一组本地服务选项在 cloud 模式下被忽略来自 src/memu/cli.py 的_add_common_options。每个命令行参数都有对应的MEMU_*环境变量CI 或 Agent 只需配置一次环境即可选项环境变量默认值说明--providerMEMU_EMBED_PROVIDERopenaiembedding 提供商标识如openai、jina、voyage--embed-modelMEMU_EMBED_MODEL取 provider 默认模型覆盖 embedding 模型--base-urlMEMU_BASE_URL取 provider 端点API base URL 覆盖--api-keyMEMU_API_KEY取 provider 的密钥变量如OPENAI_API_KEYAPI key 值或环境变量名--dbMEMU_DB./data/memu.sqlite3SQLite 文件路径、postgres://DSN 或:memory:--json—关打印原始 JSON 响应关于--dbsrc/memu/env.py 的database_config说明了取值范围裸 SQLite 路径、完整 SQLAlchemy URLsqlite:///…、postgres://…或内存哨兵值:memory:/inmemory。裸路径会自动创建父目录。本地与云端双模式本地模式默认不设任何记忆模式变量时引擎在本地构建MemoryServiceembedding 在客户端计算元数据与向量写入MEMU_DB指定的 SQLite或 Postgres DSN。这里有一个容易踩坑的点src/memu/env.py 的模块注释解释得很清楚写入侧record与检索侧inject必须使用同一个 DSN 和同一个 embedding provider否则查询向量与被比较向量处于不同的向量空间检索会静默返回空结果。因此配置解析遵循三级顺序进程环境变量MEMU_DB… memu retrieve …可一次性覆盖无需改文件~/.memu/config.env安装时写入的 dotenv可用MEMU_CONFIG_ENV改路径——定时任务没有可靠的工作目录也不继承交互式 shell绝对路径下的文件是唯一稳健的载体代码内默认值。Cloud 模式设置两个变量即可让完全相同的命令改走 MemU Cloudexport MEMU_MEMORY_MODEcloud export MEMU_CLOUD_API_KEYmemu-api-keyAPI key 需在 memu.so 注册后获取生产 API base 默认为https://api.memu.so/api/v4/memory/可用MEMU_CLOUD_BASE_URL覆盖以对接兼容部署见 src/memu/cloud.py 的DEFAULT_CLOUD_BASE_URL与 src/memu/env.py本地 embedding 配置MEMU_EMBED_PROVIDER、MEMU_EMBED_MODEL、MEMU_DB等与云端凭证完全独立、互不复用cloud 模式下本地专用选项被忽略见build_agentic_memory_backend_from_envsrc/memu/env.py能力边界Cloud 目前持久化 memory 与 skill 召回文件但不持久化提交的工作区资源MEMU_MEMORY_MODE只接受local/cloud其他取值直接抛ConfigErrorcloud 模式下缺少MEMU_CLOUD_API_KEY同样显式报错而不是猜测。从 src/memu/cloud.py 的CloudMemoryClient还可以看到几个实现细节对排障很有用三个操作list_all_recall_files/progressive_retrieve/commit_results分别映射为GET带cursor分页参数、POST search、POSTpayload 为{user, recall_files, resource}鉴权头为Authorization: Bearer key默认 3 次尝试、超时 30s连接 5s对可重试状态码做指数退避重试max_attempts最小为 1作用域where只支持user_id与agent_id的精确过滤缺省值为defaultuser字段仅支持user_id、agent_id、user_name、agent_name其他字段会抛出配置错误错误按状态码分类401 认证失败、403 授权失败、400/409/422 请求被拒、429 限流其余归为服务错误支持MEMU_HTTP_PROXY显式代理未设置时默认绕过代理的 mount 规则~/.memu/config.env中的NO_PROXY/no_proxy会被透传进进程环境src/memu/env.py。embedding 配置memU 唯一的模型能力因为 memU 内部没有 LLMMEMU_EMBED_PROVIDER命名的就是唯一剩下的模型能力。src/memu/embedding/defaults.py 是 provider 知识的单一来源内置五个后端均在 src/memu/embedding/backends/ 下有真实实现provider默认模型端点密钥环境变量openaitext-embedding-3-small字段默认值OPENAI_API_KEYjinajina-embeddings-v3https://api.jina.ai/v1JINA_API_KEYvoyagevoyage-3.5https://api.voyageai.com/v1VOYAGE_API_KEYdoubaodoubao-embedding-large-text-250515https://ark.cn-beijing.volces.comARK_API_KEYopenrouteropenai/text-embedding-3-smallhttps://openrouter.aiOPENROUTER_API_KEYprovider 的解析还带一个兼容性细节MEMU_LLM_PROVIDER作为MEMU_EMBED_PROVIDER的后备被读取让旧版~/.memu/config.env继续可用见 src/memu/env.py。npm shim 如何拉起 Python四级回退策略npm/package.json 声明了bin入口memu - bin/memu.js且files只包含bin目录——整个 npm 包就是 npm/bin/memu.js 这一个几十行的 Node 脚本。它按优先级依次探测并委派$MEMU_PYTHON -m memu——显式解释器覆盖适合自定义虚拟环境uvx --from memu-cli memu——无需安装、由 uv 缓存官方推荐路径pipx run --spec memu-cli memu——无需安装、由 pipx 缓存python3 -m memu——要求已执行pip install memu-cli。探测逻辑本身也很直接has(cmd)用spawnSync(cmd, [--version])判断可执行文件存在且退出码为 0第 4 级还会先python3 -c import memu确认包已安装才使用。若四级全部落空脚本打印安装指引安装 uv / pipx / 或 pip 安装或用MEMU_PYTHON指向已装 memU 的解释器并以退出码 1 结束。子进程的退出码会原样透传给用户stdio 直接继承。已经使用 Python 的用户可以完全跳过 npmnpm 层只是分发糖。若环境中已有 Python可以uvx --from memu-cli memu --help # 无需安装uv 缓存 # 或 pip install memu-cli同一个 PyPI 包还携带库 APIMemoryService、Postgres 后端——一次安装同时覆盖 CLI、宿主适配器与库调用。从 pyproject.toml 的[project.scripts]可以看到完整的可执行入口面除核心memu算法面外还有memu-codex、memu-claude-code、memu-cursor、memu-openclaw、memu-hermes、memu-workbuddy、memu-cola、memu-pi等宿主适配器二进制以及用于任意 Agent 的memu-agent通用适配器ADR 0008/0009/0010/0011 描述的设计。核心memu二进制的retrieve/list-files/commit用法与npx memu-cli完全一致。小结npx memu-cli的价值在于把Python 引擎 运行时管理封装成一条 npx 命令npm 启动器npm/bin/memu.js负责按MEMU_PYTHON→uvx→pipx→python3的顺序找到可用运行时PyPI 引擎入口memu.cli:main负责实际的 commit/retrieve/list-files 语义MEMU_*环境变量统一了本地与云端两条路径的配置面。对 CI 与 Agent 集成而言配置一次环境、只传命令正是这套设计的直接收益而 embedding-only、零 LLM 调用的检索路径则是它可以在低延迟、低成本前提下被高频调用的原因。项目采用 Apache-2.0 许可见 LICENSE.txt。【免费下载链接】memUPersonal memory across agents项目地址: https://gitcode.com/GitHub_Trending/mem/memU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
