@wanxiangyu/memora

v0.1.3

Published

12 days ago

Memora desktop memory space for AI coding workflows.

Downloads

568

0High
0Medium
0Low

wanxiangyu

Memora 使用文档

Memora 是一个本地优先的 AI 编程记忆管理工具。它包含两个入口：

memora：打开桌面端，用来查看、搜索、编辑、导入导出和拖拽管理记忆。
memora-mcp：启动 MCP stdio server，供 Codex、Claude Code 或其他 MCP Host 调用。

桌面端和 MCP 默认读写同一份本地 JSON 记忆库。AI 工具不需要读取桌面 UI，它们通过 MCP 工具保存和检索记忆。MCP 默认按当前工作目录隔离记忆，只有在桌面端拖拽共享后，另一个 workspace 才能读到共享副本。

快速开始

npm install -g @wanxiangyu/memora
memora

配置 Codex：

codex mcp add memora -- memora-mcp

重启 Codex 后执行：

/mcp

应该看到：

list_memory_projects
get_current_workspace
recall_memories
save_memory

从 npm 安装

npm install -g @wanxiangyu/memora

安装后有两个命令：

memora

打开桌面端。

memora-mcp

启动 MCP stdio server。这个命令通常由 Codex 或 Claude Code 自动启动，手动运行时没有输出是正常的。

不要把 memora-mcp 包在 npm run 里给 MCP Host 使用。MCP stdio 的 stdout 必须只传 JSON-RPC 协议数据，npm run 会输出脚本文字，可能导致 MCP 超时或没有工具。

Codex 配置

npm 安装后：

codex mcp add memora -- memora-mcp

指定记忆文件：

codex mcp add memora --env MEMORA_STORE_PATH=/absolute/path/memories.json -- memora-mcp

源码模式：

cd /absolute/path/to/memora
npm install
npm run build
codex mcp remove memora
codex mcp add memora -- node "$(pwd)/apps/desktop/bin/memora-mcp.js"

等价 ~/.codex/config.toml：

[mcp_servers.memora]
command = "node"
args = ["/absolute/path/to/memora/apps/desktop/bin/memora-mcp.js"]
startup_timeout_sec = 60
tool_timeout_sec = 60

不要在全局 MCP 配置里写固定的 MEMORA_PROJECT_PATH="$(pwd)"。那会把所有 Codex 工作目录都绑定到同一个 Memora workspace。

如果你的 MCP Host 没有把当前工作目录传给 memora-mcp，请在每个项目自己的 .codex/config.toml 里配置项目级 MCP：

[mcp_servers.memora]
command = "memora-mcp"
args = ["--workspace=/absolute/path/to/this/project"]
startup_timeout_sec = 60
tool_timeout_sec = 60

Claude Code 配置

npm 安装后：

{
  "mcpServers": {
    "memora": {
      "command": "memora-mcp"
    }
  }
}

源码模式：

{
  "mcpServers": {
    "memora": {
      "command": "node",
      "args": ["/absolute/path/to/memora/apps/desktop/bin/memora-mcp.js"]
    }
  }
}

使用指定记忆文件：

{
  "mcpServers": {
    "memora": {
      "command": "memora-mcp",
      "env": {
        "MEMORA_STORE_PATH": "/absolute/path/memories.json"
      }
    }
  }
}

从源码运行

cd /absolute/path/to/memora
npm install
npm run build

开发模式启动桌面端：

npm run dev:desktop

源码构建后，以接近 npm 包的方式启动：

npm -w @wanxiangyu/memora run start

质量检查：

npm run typecheck
npm test
npm -w @wanxiangyu/memora run test:e2e

检查 npm 包内容：

npm -w @wanxiangyu/memora pack --dry-run

记忆数据位置

默认路径：

macOS：~/Library/Application Support/Memora/memora-data/memories.json
Windows：%APPDATA%\Memora\memora-data\memories.json
Linux：${XDG_CONFIG_HOME:-~/.config}/Memora/memora-data/memories.json

指定完整文件：

MEMORA_STORE_PATH=/absolute/path/memories.json memora

指定目录：

MEMORA_DATA_DIR=/absolute/path/memora-data memora

桌面端和 MCP 都支持 MEMORA_STORE_PATH 和 MEMORA_DATA_DIR。如果两边看不到同一条记忆，优先确认它们使用的是同一个路径。

项目隔离

Memora MCP 按“当前工作目录 = workspace”隔离记忆。新版 MCP 不再只依赖服务启动目录，因为全局 MCP 配置、npm --prefix 或 MCP 客户端复用进程时，启动目录可能一直是同一个。

实际规则：

save_memory、recall_memories 和 get_current_workspace 的工具参数必须带 workspace_path，值是当前 Codex/Claude Code 会话的绝对工作目录。
Memora 把 workspace_path 转成稳定项目 id，例如 /Users/wanxiang/test 会成为 users-wanxiang-test。
--workspace=... 或 --project=... 只用于你明确想把某个 MCP 配置固定到一个项目的情况。
如果没有显式 --workspace，并且工具调用没有传 workspace_path，新版会报错，避免继续把多个项目写进同一个 workspace。

默认行为：

save_memory 永远保存到 workspace_path 对应的 workspace；AI 传入的旧 project 字段会被忽略。
recall_memories 永远只搜索 workspace_path 对应的 workspace；AI 传入的 scope 或 filters.project 会被忽略。
get_current_workspace 可以诊断当前 cwd 会映射到哪个 Memora 项目。
list_memory_projects 可以查看项目计数，但不返回记忆正文。

拖拽共享会复制一条记忆到目标项目，所以目标项目能读到共享后的副本是正常的；原项目仍保留原记忆。

基本使用流程

启动桌面端：

memora

配置 MCP：

codex mcp add memora -- memora-mcp

在 Codex 或 Claude Code 中保存记忆：

使用 Memora MCP 保存一条记忆：这个项目使用 JSON 作为 V1 存储，不需要 SQLite。

在桌面端查看。

切到 Global/全局，清空搜索词，点击顶栏刷新按钮。MCP 新写入的记忆会出现在列表和记忆空间里。

检索记忆：

调用 Memora 的 recall_memories，搜索 “JSON V1 存储”。

DeepSeek LLM 蒸馏

Memora 的“蒸馏”按钮只使用 DeepSeek V4 LLM 蒸馏，不再使用本地关键词/分段规则生成记忆。真实桌面端调用路径是：

React UI -> Electron IPC -> DeepSeek Chat Completions -> 本地 JSON 记忆库

默认配置：

默认模型：deepseek-v4-pro
可选模型：通过 MEMORA_DEEPSEEK_MODEL=deepseek-v4-flash 切换
默认接口：https://api.deepseek.com/chat/completions
Key 环境变量：优先 MEMORA_DEEPSEEK_API_KEY，其次 DEEPSEEK_API_KEY

源码启动：

MEMORA_DEEPSEEK_API_KEY="你的 DeepSeek Key" npm run dev:desktop

npm 安装后启动：

MEMORA_DEEPSEEK_API_KEY="你的 DeepSeek Key" memora

不要把 API key 写进源码或 npm 包。npm 包发布后任何人都能解包读取 key，等同于公开泄露。

桌面端功能

搜索和类型筛选。
全局记忆和项目记忆切换。
编辑、删除、恢复记忆。
删除项目组：普通视图会把当前项目的活跃记忆移入垃圾箱；垃圾箱视图可永久删除当前项目的已删除记忆。
JSON 导入导出，Markdown 导出。
拖拽记忆卡片到项目，完成项目间共享。
中英文切换。
MCP 写入后自动刷新，也可以手动点击顶栏刷新按钮。

MCP 工具

`save_memory`

记忆会保存到当前 MCP workspace。即使 AI 传入 project 字段，Memora 也会忽略它，避免串项目。

{
  "title": "Repository before SQLite",
  "content": "V1 使用 JSON Repository，后续如果需要 SQLite，应保持同一 Repository 接口。",
  "type": "decision",
  "workspace_path": "/absolute/path/to/current/project",
  "tags": ["storage", "architecture"]
}

`get_current_workspace`

诊断当前工作目录会映射到哪个 Memora 项目。

{
  "workspace_path": "/absolute/path/to/current/project"
}

`recall_memories`

只搜索当前 MCP workspace。跨 workspace 共享需要在桌面端拖拽记忆卡片完成。

{
  "query": "SQLite JSON Repository",
  "workspace_path": "/absolute/path/to/current/project",
  "limit": 10,
  "filters": {
    "type": "decision",
    "tags": ["storage"]
  }
}

`list_memory_projects`

{
  "workspace_path": "/absolute/path/to/current/project",
  "includeDeleted": true
}

发布说明

当前主包名是 @wanxiangyu/memora，它依赖多个 @wanxiangyu/memora-* workspace 包。正式发布时需要先发布内部包，再发布 @wanxiangyu/memora 主包，或者调整打包策略把内部包打进主包。

发布前检查：

npm run build
npm test
npm -w @wanxiangyu/memora pack --dry-run

发布顺序示例：

npm publish -w @wanxiangyu/memora-shared --access public
npm publish -w @wanxiangyu/memora-core --access public
npm publish -w @wanxiangyu/memora-storage --access public
npm publish -w @wanxiangyu/memora-retrieval --access public
npm publish -w @wanxiangyu/memora-distillation --access public
npm publish -w @wanxiangyu/memora-mcp --access public
npm publish -w @wanxiangyu/memora --access public

常见问题

`Cannot find module '/workspace/projects/...'`

你复制了别人机器或容器里的绝对路径。请在你的本机项目根目录执行：

pwd

然后把输出的真实路径写进 MCP 配置。

Codex 显示 `Tools: (none)` 或 MCP 超时

按顺序检查：

是否已经 npm run build。
是否重启了 Codex。
codex mcp get memora 里是否是 command: node 或 command: memora-mcp。
不要使用 npm run 包装 MCP server。

两个不同项目的记忆显示在同一个项目里

新版 Memora 会要求 save_memory / recall_memories 的工具参数带 workspace_path。如果仍然合并，通常是还在运行旧版 MCP，或者工具调用没有按新版 schema 传当前 cwd。

先在两个不同 Codex 项目里分别调用：

调用 Memora 的 get_current_workspace，workspace_path 使用当前项目绝对路径。

如果两个项目返回同一个 project，继续检查配置：

codex mcp get memora

如果看到固定项目路径，并且你不是有意把 MCP 固定到单个项目，删除后重配：

codex mcp remove memora
codex mcp add memora -- memora-mcp

源码模式：

codex mcp remove memora
codex mcp add memora -- node "/absolute/path/to/memora/apps/desktop/bin/memora-mcp.js"

如果 MCP Host 不能按工具 schema 传 workspace_path，就在每个项目的 .codex/config.toml 中写项目级配置：

[mcp_servers.memora]
command = "memora-mcp"
args = ["--workspace=/absolute/path/to/this/project"]
startup_timeout_sec = 60
tool_timeout_sec = 60

MCP 保存成功，但桌面端看不到

按顺序检查：

桌面端点击刷新按钮。
切到 Global/全局。
清空搜索框。
确认不是垃圾箱视图。
确认桌面端和 MCP 使用同一个 MEMORA_STORE_PATH。
完全退出桌面端后重新打开。

手动运行 `memora-mcp` 没有输出

正常。它是 stdio MCP server，会等待 MCP Host 发送 JSON-RPC 请求。

开发模式出现 Developer Tools

只有开发模式可能打开调试工具。发布后的 memora 不会默认打开 Developer Tools。

npm 安装时一直显示 installing

这是 Electron 运行时在下载对应平台的桌面端二进制文件，首次安装会比较慢。它和 Memora 数据同步无关，通常等待下载完成即可。

如果安装长时间卡住，优先检查网络是否能访问 npm registry 和 Electron 下载源。后续更适合给普通用户提供 .dmg、.exe、.AppImage 这类原生安装包，npm 包更适合开发者和 CLI/MCP 用户。

启动后黑屏

请先升级到最新版本：

npm install -g @wanxiangyu/memora@latest

如果仍然黑屏，可以用调试模式启动并查看控制台错误：

MEMORA_OPEN_DEVTOOLS=1 memora

卸载

npm uninstall -g @wanxiangyu/memora
codex mcp remove memora

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Memora 使用文档

快速开始

从 npm 安装

Codex 配置

Claude Code 配置

从源码运行

记忆数据位置

项目隔离

基本使用流程

DeepSeek LLM 蒸馏

桌面端功能

MCP 工具

save_memory

get_current_workspace

recall_memories

list_memory_projects

发布说明

常见问题

Cannot find module '/workspace/projects/...'

Codex 显示 Tools: (none) 或 MCP 超时

两个不同项目的记忆显示在同一个项目里

MCP 保存成功，但桌面端看不到

手动运行 memora-mcp 没有输出

开发模式出现 Developer Tools

npm 安装时一直显示 installing

启动后黑屏

卸载

`save_memory`

`get_current_workspace`

`recall_memories`

`list_memory_projects`

`Cannot find module '/workspace/projects/...'`

Codex 显示 `Tools: (none)` 或 MCP 超时

手动运行 `memora-mcp` 没有输出