OMMS — Opinionated Modular Memory System

OMMS gives your AI coding agent a long-term memory. As you work, it writes short notes about what was done and decided in each project: fixes, design choices, things that did not work. It brings the relevant notes back in later sessions, so the agent does not start from zero every time. It also learns how you like to work and keeps that as a user profile.

It runs inside OpenCode and the Pi coding agent. Both share one memory per project, so a note written in one is available in the other. Everything is stored locally on your machine.

What it does

• Remembers automatically. After each piece of work, a background model call summarises it into a memory. You do not have to ask.
• Recalls when relevant. Matching memories are added to the agent's context: on every prompt in OpenCode v2 and Pi, at the start of a session in OpenCode v1.
• Learns your preferences. A user profile of your habits builds up over time and follows you across projects.
• Imports your past sessions. One command turns old OpenCode or Pi history into memories and a profile.
• Lets you look and edit. A local web page shows every memory and your profile.
• Keeps private things private. Text inside <private> tags is never stored.

Before you start

You need one of:

• OpenCode 1.18.29 or later (v1 plugin API) or OpenCode v2
• Pi coding agent

Nothing else is required. OMMS brings its own database. On first use it downloads a small embedding model (the part that makes memories searchable), so you need internet access once. The terminal import command also needs Node.js 22.14 or later.

Set up

1. Install

OpenCode. Add om-memory-system to ~/.config/opencode/opencode.json (on Windows, %USERPROFILE%\.config\opencode\opencode.json):

// OpenCode v2
{ "plugins": ["om-memory-system"] }

// OpenCode v1
{ "plugin": ["om-memory-system"] }

On OpenCode v2 you can run opencode plugin add om-memory-system instead. Restart OpenCode.

Pi. Run:

pi install npm:om-memory-system

Restart Pi. You can install OMMS in both agents; they share the same memory.

2. Choose which model writes memories (optional)

With no settings, OMMS uses the model of the session you are working in. To use a different one, add it to ~/.config/omms/omms.jsonc. If you have no config file yet, OMMS creates this one with comments on first start.

{
  // A model you are already signed in to in OpenCode or Pi.
  // Use "inherit" to always follow the session's model.
  "opencodeProvider": "openai",
  "opencodeModel": "gpt-5.6-luna",
  "piProvider": "openai-codex",
  "piModel": "gpt-5.6-luna",
}

You can also use any OpenAI-compatible or Anthropic API with your own key. See Configuration.

3. Check it works

Work normally for a few turns, then open http://127.0.0.1:4747 in your browser (OpenCode serves this page). New memories appear on the timeline. You can also ask the agent: "search memory for what we changed today".

Import your past history

To turn earlier sessions into memories, preview first and then run it inside the agent:

/memory-import-opencode-history --dry-run
/memory-import-pi-history --dry-run

The preview shows how many model calls a real import needs. It uses the session's model; add --model provider/id for a cheaper one. There is also a terminal version, npx om-memory-system, that uses an API key. See the OpenCode and Pi import guides, and the CLI reference.

Keeping OMMS up to date

Pi shows a notice when a new version is out; update with pi update npm:om-memory-system. On OpenCode v2, run opencode plugin check and opencode plugin update om-memory-system. Restart the agent afterwards. To stay on one version, install it with the number, for example pi install npm:om-memory-system@3.1.1 or opencode plugin add om-memory-system@3.1.1; a pinned install is never updated. Coming from opencode-mem? Your memories move over automatically, with a backup first. See Updating and upgrading and CHANGELOG.md.

Documentation

Read this	To learn about
Using memory day to day	How capture and recall work, the memory tool, the user profile
Configuration	Settings, choosing the model, embeddings, troubleshooting
Web UI	The memory explorer, opening it on a network safely
Moving projects	Nested repositories, moved folders, backup and restore
Updating and upgrading	Updates, pinning a version, older stores
OpenCode adapter	How the OpenCode plugin hooks in
Pi adapter	How the Pi extension hooks in
OpenCode history import	Importing past OpenCode sessions
Pi history import	Importing past Pi sessions, moving machines
CLI reference	The om-memory-system terminal command
Migrating from opencode-mem	What changes when upgrading from the original plugin
For developers	Building, testing, the public tags export, architecture
Contributing	How to set up, test, and send a pull request

About this fork

OMMS is cmdaltctr/omms, a fork of tickernelz/opencode-mem, published on npm as om-memory-system. The fork runs the memory engine as a shared core for both OpenCode and Pi (see shared core). Existing OpenCode memories and settings keep working.

License and links

MIT License. See LICENSE.md.

• Repository: https://github.com/cmdaltctr/omms
• Upstream: https://github.com/tickernelz/opencode-mem
• Issues: https://github.com/cmdaltctr/omms/issues

Inspired by opencode-supermemory.