Package Exports

nomi-agent

Readme

nomi-agent

English | 中文

Long-term memory for OpenCode — remember preferences, decisions, patterns and lessons across sessions.

Installation

Prerequisites

Node.js ≥ 20 — Download here
OpenCode installed and configured

Install Nomi

npx nomi-agent install

This single command downloads and installs Nomi into your OpenCode global config. No separate npm install needed — npx handles everything automatically.

Restart OpenCode after installation. Nomi will start injecting your memories into every session immediately.

Prefer a permanent global install?
npm install -g nomi-agent
nomi-agent install

Verify installation

After restarting OpenCode, ask the agent:

remember this: I prefer concise code comments

If Nomi responds with a confirmation, the installation is working.

What it does

Nomi gives OpenCode AI a persistent memory store. The agent automatically:

Remembers preferences, decisions, patterns, and lessons you tell it
Recalls relevant context at the start of each session
Injects up to ~1500 tokens of relevant memories into the system prompt

Memories are stored locally in a JSONL file at:

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

Override the path with NOMI_MEMORY_PATH=/your/path.

CLI reference

npx nomi-agent install    # Install into OpenCode global config
npx nomi-agent update     # Reinstall after upgrading the package
npx nomi-agent uninstall  # Remove all installed files
npx nomi-agent dashboard  # Launch the web dashboard (http://localhost:3210)

What `install` does

Copies compiled runtime to ~/.config/opencode/nomi/
Runs npm install inside that directory to resolve @opencode-ai/plugin
Writes generated plugin/tool files into your OpenCode config:
- ~/.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

Memory categories

Category	Use for
`preference`	Communication style, code style preferences
`decision`	Technology choices and the reasoning behind
`pattern`	Project conventions, naming, code patterns
`lesson`	Bugs fixed, pitfalls to avoid next time
`context`	Project background, key dependencies, paths

Local Dashboard

Nomi includes a local web dashboard for browsing and managing your memories.

npx nomi-agent dashboard

Available at http://localhost:3210 — override the port with NOMI_API_PORT=<port>.

The dashboard supports: memory list/search/filter/create/edit/delete/import/export/stats, plus a task panel for dispatched sessions with queue status, task detail, batch summaries, graph summaries, visible message snippets, and diff summaries.

Configuration

Environment variable	Default	Description
`NOMI_MEMORY_PATH`	`~/.config/opencode/nomi/memories.jsonl`	Where memories are stored
`NOMI_TASKS_PATH`	`~/.config/opencode/nomi/tasks.jsonl`	Where dispatched task records are stored
`NOMI_GRAPHS_PATH`	`~/.config/opencode/nomi/graphs.jsonl`	Where DAG orchestration graph records are stored
`OPENCODE_CONFIG_DIR`	`~/.config/opencode`	Override OpenCode config root
`NOMI_INJECTION_LIMIT`	`15`	Max number of memories injected per session
`NOMI_TOKEN_BUDGET`	`1500`	Token budget for memory injection (in tokens)
`NOMI_SEMANTIC_SEARCH`	`true`	Enable semantic recall ranking
`NOMI_SEMANTIC_PROVIDER`	`hash`	Semantic provider (`hash` or `transformers`)
`NOMI_SEMANTIC_MODEL`	`onnx-community/all-MiniLM-L6-v2-ONNX`	Model used when provider is `transformers`
`NOMI_SEMANTIC_CACHE_DIR`	`~/.config/opencode/nomi/models`	Local cache for downloaded embedding models
`NOMI_SEMANTIC_MIN_SCORE`	`0.35`	Minimum semantic score to include a recall match
`NOMI_API_PORT`	`3210`	Dashboard server port (`npx nomi-agent dashboard`)

How injection works

At the start of each session the plugin selects memories up to a ~1500-token budget, in priority order:

Global preference memories
Memories tagged with the current project directory
High-hit-count global memories

Roadmap

Status	Feature	Description
✅ Done	`remember` / `recall` tools	Agent-callable memory save and search
✅ Done	Auto-capture	Detects "remember this: X" patterns automatically
✅ Done	Session injection	Memories injected into system prompt on session start
✅ Done	Local Dashboard	Web UI for browsing, editing, and managing memories
✅ Done	CLI installer	`npx nomi-agent install` one-command setup
✅ Done	`forget` tool	Let the agent delete memories through conversation
✅ Done	`list` tool	Let the agent enumerate memories without a search query
✅ Done	Configurable injection budget	`NOMI_INJECTION_LIMIT` / `NOMI_TOKEN_BUDGET` env vars
✅ Done	Memory expiration / TTL	`expires_at` field — expired memories are excluded from injection and recall
✅ Done	Passive auto-learning	Extracts implicit preferences from assistant responses ("I'll always…", "Going forward…", etc.); disable with `NOMI_PASSIVE_CAPTURE=false`
✅ Done	Multi-project task dispatch	`dispatch_task(directory, prompt)` tool — spawn an OpenCode session in any directory and send a prompt non-interactively via `Session.promptAsync()`
✅ Done	Task lifecycle tools	`task_status` / `task_result` / `task_abort` / `list_tasks` — monitor and manage dispatched sessions; state persisted in `tasks.jsonl`
✅ Done	Semantic search	Local semantic recall ranking with offline-first hash embeddings and optional Transformers.js provider
✅ Done	Dashboard task panel	nomi-dashboard now exposes a task queue view with task detail, batch summaries, graph summaries, visible message snippets, and diff summaries
✅ Done	Cross-session context passing	A completed task's diff/message summary can be injected into the next dispatched session as an opening handoff block
✅ Done	Memory injection into sub-agents	Dispatched child sessions now receive an explicit project-scoped memory block via the session opening system prompt
✅ Done	Parallel multi-repo execution	`dispatch_tasks` fans out the same prompt to N directories and `batch_status` / `batch_result` aggregate progress and diffs
✅ Done	DAG task orchestration	`dispatch_task_graph` persists dependency graphs and launches downstream nodes automatically when prerequisites complete
⚠️ Blocked (upstream / missing remote manager)	Workspace adapter integration	OpenCode `experimental_workspace.register()` exists, but Nomi does not yet manage remote instance lifecycle/endpoints; routing the native workspace switcher to real Nomi-managed remotes is not safely implementable in this repo yet

Workspace adapter status

This repository now has the task, batch, graph, handoff, and dashboard layers needed for orchestration, but it still does not have a remote-instance control plane.

As of this implementation:

OpenCode's workspace adapter API is still experimental upstream
Nomi has no server/container/sandbox provisioner to create and delete remote runtimes
Nomi has no durable registry of remote workspace URLs, auth headers, or lifecycle state

So a true WorkspaceAdapter integration for "Nomi-managed remote instances" would be incomplete and misleading today. It should be revisited only after a dedicated remote runtime manager exists in-repo.

Contributing

git clone https://github.com/Zengxiaoer991214/nomi-agent.git
cd nomi-agent
npm install
npm run check   # typecheck
npm run build   # compile to dist/

Project layout:

src/
  memory/        # Core memory store (JSONL CRUD + search)
  plugins/       # OpenCode plugin definition
  tools/         # remember / recall tool definitions
cli/
  install.ts     # npx installer
nomi-dashboard/  # Local React dashboard (private, not published)
.opencode/       # Project-local OpenCode config (for development)

JSPM

nomi-agent

Package Exports

Readme

nomi-agent

Installation

Prerequisites

Install Nomi

Verify installation

What it does

CLI reference

What `install` does

Memory categories

Local Dashboard

Configuration

How injection works

Roadmap

Workspace adapter status

Contributing

License

nomi-agent

Package Exports

Readme

nomi-agent

Installation

Prerequisites

Install Nomi

Verify installation

What it does

CLI reference

What install does

Memory categories

Local Dashboard

Configuration

How injection works

Roadmap

Workspace adapter status

Contributing

License

What `install` does