OMMS: Opinionated Modular Memory System

OMMS gives AI coding agents long-term project memory. It captures technical work, recalls relevant notes in later sessions and learns your working preferences. One shared engine serves OpenCode, Pi and Claude Code, so each host can retrieve memories captured by the others in the same project.

Memories are stored locally, by default in ~/.omms/data. Embeddings run locally by default; the first use downloads a search model. Capture and profile learning make additional model calls that can send conversation content to your chosen provider and incur costs. Remote embeddings are optional. OMMS removes text inside <private> tags before storage. See Configuration for model choices and privacy controls.

Set up

Use Node.js 22.14 or later for the terminal command and Claude Code hooks. OpenCode v1 needs 1.18.29 or later. OMMS also supports OpenCode v2 and the Pi coding agent.

Automatic history import is enabled by default and makes model calls. To disable it before your first session, set "autoBackfill": false in ~/.config/omms/omms.jsonc. See Automatic import.

OpenCode

Add the package to ~/.config/opencode/opencode.json. Keep your existing settings. On Windows, use %USERPROFILE%\.config\opencode\opencode.json.

OpenCode v2:

{ "plugins": ["om-memory-system"] }

OpenCode v1:

{ "plugin": ["om-memory-system"] }

OpenCode v2 also supports:

opencode plugin add om-memory-system

Restart OpenCode. The OpenCode guide covers plugin management and its additional cli.json configuration.

Pi

pi install npm:om-memory-system

Restart Pi. See the Pi guide.

Claude Code

Install the OMMS plugin using the Claude Code guide. Capture and profile learning require a configured external API; retrieval and manual memory operations remain available without it. A global npm install is optional.

Model and web app

With no model settings, OpenCode and Pi use the session model. You can choose a host model or configure an external API under Settings. Claude Code uses only the external API. See Choosing the model for the selection order and credentials.

Start a host session, then open http://127.0.0.1:4747. Each host starts the shared web app when needed, unless it is disabled. Browse captured notes on Project memories, or ask your agent to search memory for an earlier decision.

Terminal command (optional)

A global install puts om-memory-system on your PATH:

npm install -g om-memory-system
om-memory-system --version

See the CLI reference for manual memory operations and history imports.

Inside OMMS

These screenshots use synthetic examples and configuration. All visible prompts, code snippets and outcomes are made up for the demonstration.

Project memories

Browse captured notes alongside example user input and technical outcomes.

Memory

Pick a host card (Pi, OpenCode or Claude Code) to see its import status, sessions and folders that need a map. The Shared card holds profile learning, memory limits and other settings that apply to every host. The cards also warn you when memories cannot be saved.

Settings

Choose models and manage access. Diagnostics show capture outcomes and component health.

Documentation

Guide	Covers
Using memory	Daily use, capture, recall and the user profile
Web UI	Starting the app, browsing memories and safe network access
Memory page	One card per host, imports, shared settings and avatars
Settings page	Models, credentials, diagnostics and profile identities
Configuration	Config files, model selection, privacy and embeddings
Moving projects	Folder moves, backup and restore
Updating and upgrading	Updates, version pinning and older stores
CLI reference	Terminal commands
For developers	Building, testing and architecture
Contributing	Development workflow and pull requests

History import guides: OpenCode, Pi and Claude Code. See UPDATES.md for host update commands and CHANGELOG.md for release changes. Existing opencode-mem users can follow the migration guide.

Licence

MIT. See LICENSE.md for copyright and attribution, and THIRD_PARTY_NOTICES.md for bundled dependencies.

Repository · Issues · Documentation index