nomi-agent

English | 中文

为 OpenCode 提供长期记忆——跨会话记住你的偏好、决策、模式和经验教训。

安装

前置条件

• Node.js ≥ 20 — 点此下载
• 已安装并配置 OpenCode

安装 Nomi

npx nomi-agent install

一条命令即可完成下载和安装，无需单独执行 npm install——npx 会自动处理一切。

安装完成后重启 OpenCode，Nomi 会立即开始在每次会话中自动注入你的记忆。

喜欢永久全局安装？

npm install -g nomi-agent
nomi-agent install

验证安装

重启 OpenCode 后，向 Agent 发送：

remember this: I prefer concise code comments

如果 Nomi 给出确认回复，则安装成功。

功能介绍

Nomi 为 OpenCode AI 提供持久化的记忆存储，Agent 会自动：

• 记录 你告诉它的偏好、决策、模式和经验
• 回忆 每次会话开始时的相关上下文
• 注入 最多约 1500 token 的相关记忆到系统提示中

记忆默认以 JSONL 文件存储在本地：

~/.config/opencode/nomi/memories.jsonl

可通过 NOMI_MEMORY_PATH=/your/path 覆盖路径。

CLI 命令

npx nomi-agent install    # 安装到 OpenCode 全局配置
npx nomi-agent update     # 升级包后重新安装
npx nomi-agent uninstall  # 移除已安装文件（记忆数据保留）
npx nomi-agent dashboard  # 启动 Web Dashboard（http://localhost:3210）
npx nomi-agent purge      # ⚠️  永久删除所有数据（需要 --yes 确认）

install 做了什么

1. 将编译后的运行时复制到 ~/.config/opencode/nomi/
2. 在该目录内运行 npm install 以解析 @opencode-ai/plugin
3. 在你的 OpenCode 配置中写入生成的插件/工具文件：
   • ~/.config/opencode/plugins/nomi-memory.ts
   • ~/.config/opencode/tools/remember.ts
   • ~/.config/opencode/tools/recall.ts
   • ~/.config/opencode/tools/forget.ts
   • ~/.config/opencode/tools/list.ts
   • ~/.config/opencode/tools/dispatch_task.ts
   • ~/.config/opencode/tools/dispatch_tasks.ts
   • ~/.config/opencode/tools/dispatch_task_graph.ts
   • ~/.config/opencode/tools/open_task.ts
   • ~/.config/opencode/tools/batch_status.ts
   • ~/.config/opencode/tools/batch_result.ts
   • ~/.config/opencode/tools/graph_status.ts
   • ~/.config/opencode/tools/task_status.ts
   • ~/.config/opencode/tools/task_result.ts
   • ~/.config/opencode/tools/task_abort.ts
   • ~/.config/opencode/tools/list_tasks.ts
   • ~/.config/opencode/agents/nomi.md

记忆分类

| 分类 | 适用场景 | | ------------ | -------------------------------- | | preference | 沟通风格、代码风格偏好 | | decision | 技术选型及背后的原因 | | pattern | 项目约定、命名规范、代码模式 | | lesson | 修复的 Bug、下次要避免的坑 | | context | 项目背景、关键依赖、重要路径 |

本地 Dashboard

Nomi 内置一个本地 Web Dashboard，用于浏览和管理你的记忆。

npx nomi-agent dashboard

访问 http://localhost:3210 — 可通过 NOMI_API_PORT=<端口> 自定义端口。

Dashboard 现已支持：记忆的列表/搜索/按分类筛选/创建/编辑/删除/批量删除/导入/导出/统计，以及任务面板（任务队列、任务详情、batch 汇总、graph 汇总、可见消息摘要、diff 摘要）。

配置项

| 环境变量 | 默认值 | 说明 | | ----------------------- | ---------------------------------------- | ---------------------------------------- | | NOMI_MEMORY_PATH | ~/.config/opencode/nomi/memories.jsonl | 记忆文件存储路径 | | NOMI_TASKS_PATH | ~/.config/opencode/nomi/tasks.jsonl | 已派发任务记录的存储路径 | | NOMI_GRAPHS_PATH | ~/.config/opencode/nomi/graphs.jsonl | DAG 编排图记录的存储路径 | | OPENCODE_CONFIG_DIR | ~/.config/opencode | 覆盖 OpenCode 配置根目录 | | NOMI_INJECTION_LIMIT | 15 | 每次会话最多注入的记忆条数 | | NOMI_TOKEN_BUDGET | 1500 | 注入记忆的 token 预算上限 | | NOMI_SEMANTIC_SEARCH | true | 是否启用语义召回排序 | | NOMI_SEMANTIC_PROVIDER| hash | 语义检索提供者（hash 或 transformers） | | NOMI_SEMANTIC_MODEL | onnx-community/all-MiniLM-L6-v2-ONNX | transformers 模式下使用的 embedding 模型 | | NOMI_SEMANTIC_CACHE_DIR | ~/.config/opencode/nomi/models | 下载模型的本地缓存目录 | | NOMI_SEMANTIC_MIN_SCORE | 0.35 | 语义召回命中的最低分数阈值 | | NOMI_API_PORT | 3210 | Dashboard 服务端口（npx nomi-agent dashboard） |

注入原理

每次会话开始时，插件按以下优先级选取记忆，直到填满约 1500 token 的预算：

1. 全局 preference 类记忆
2. 带有当前项目目录标签的记忆
3. 命中次数较高的全局记忆

Roadmap

| 状态 | 功能 | 说明 | |------|------|------| | ✅ 已完成 | remember / recall 工具 | Agent 可主动调用的记忆存取工具 | | ✅ 已完成 | 自动捕获 | 自动识别"记住这个：xxx"等触发词并写入记忆 | | ✅ 已完成 | 会话注入 | 每次会话开始时将记忆注入 system prompt | | ✅ 已完成 | 本地 Dashboard | 浏览、编辑、管理记忆的 Web 界面 | | ✅ 已完成 | CLI 安装器 | npx nomi-agent install 一键安装 | | ✅ 已完成 | forget 工具 | 让 Agent 通过对话删除指定记忆 | | ✅ 已完成 | list 工具 | 让 Agent 在无搜索词时枚举所有记忆 | | ✅ 已完成 | 可配置注入上限 | 支持 NOMI_INJECTION_LIMIT / NOMI_TOKEN_BUDGET 环境变量 | | ✅ 已完成 | 记忆过期 / TTL | 支持 expires_at 字段，过期记忆自动从注入和召回中排除 | | ✅ 已完成 | 被动自动学习 | 分析助手响应中的隐含偏好（"以后都…""Going forward…"等模式），无需显式触发；可通过 NOMI_PASSIVE_CAPTURE=false 禁用 | | ✅ 已完成 | 多项目任务派发 | dispatch_task(directory, prompt) 工具——向任意目录的 OpenCode session 异步发送任务，底层使用 Session.promptAsync() | | ✅ 已完成 | 任务生命周期工具 | task_status / task_result / task_abort / list_tasks——监控和管理已派发的 session，状态持久化到 tasks.jsonl | | ✅ 已完成 | 语义检索 | 本地优先的语义召回排序：默认离线 hash embedding，可选 Transformers.js provider | | ✅ 已完成 | Dashboard 任务面板 | nomi-dashboard 已提供任务队列、任务详情、batch 汇总、graph 汇总、可见消息摘要和 diff 摘要 | | ✅ 已完成 | 跨 session 上下文传递 | 可将已完成任务的 diff / 可见消息摘要注入到下一次派发 session 的开场 handoff block | | ✅ 已完成 | 子 Agent 记忆注入 | 派发出的子 session 会在 opening system prompt 中显式收到项目相关的记忆块 | | ✅ 已完成 | 并行多仓库执行 | dispatch_tasks 可并行派发到多个目录，batch_status / batch_result 负责聚合状态与 diff | | ✅ 已完成 | DAG 任务编排 | dispatch_task_graph 支持静态依赖图，前置完成后自动触发下游节点 | | ⚠️ 受阻（上游实验态 / 缺少远端管理层） | WorkspaceAdapter 集成 | OpenCode 的 experimental_workspace.register() 已存在，但 Nomi 目前还没有远端实例生命周期管理、远端地址注册与鉴权层，因此还不能安全实现“路由到 Nomi 管理的远端实例” |

WorkspaceAdapter 当前状态

现在仓内已经具备 task / batch / graph / handoff / dashboard 这些编排层能力，但仍然没有远端实例控制平面。

截至当前实现：

• OpenCode 的 workspace adapter 仍属于上游实验 API
• Nomi 自身没有容器 / 沙箱 / 远端运行时的创建与销毁能力
• Nomi 也没有远端 workspace URL、认证头、生命周期状态的持久注册表

所以如果现在硬做 WorkspaceAdapter，只能做成“接口看起来存在”，却无法真正路由到 Nomi 管理的远端实例。这会误导使用者，因此当前版本将其明确标记为受阻，待仓内补齐远端运行时管理层后再继续。

参与贡献

git clone https://github.com/Zengxiaoer991214/nomi-agent.git
cd nomi-agent
npm install
npm run check   # 类型检查
npm run build   # 编译到 dist/

项目结构：

src/
  memory/        # 核心记忆存储（JSONL 增删改查+搜索）
  plugins/       # OpenCode 插件定义
  tools/         # remember / recall 工具定义
cli/
  install.ts     # npx 安装器
nomi-dashboard/  # 本地 React Dashboard（私有，不发布到 npm）
.opencode/       # 项目本地 OpenCode 配置（开发用）

许可证

MIT © Nomi Contributors