A lightweight but powerful and layered memory system for coding agents. Currently OpenCode only, with other platforms to follow. Your knowledge lives in plain Markdown files — readable, editable, grepable, committable. The agent handles the busywork; you stay in control.

Your agent starts every session with amnesia. You tell it about your stack, your conventions, your preferences. Next session, gone. You repeat yourself. It re-discovers the same things. This is wasteful, inconsistent, and frankly boring.

OpenMemory fixes that. It gives agents a filesystem-level memory they can read, write, and maintain across sessions — no databases, no servers, no Docker. Just .md files in .openmemory/.

There are a bunch of memory plugins already. They tend to fall into two camps.

The kitchen sink. SQLite databases, vector embeddings, web dashboards, daemon processes, REST APIs. Impressive engineering, but every layer is something that can break, drift, or slow you down. When your session ends mid-flight because the daemon crashed, you're back to amnesia.

The toy. A single JSON file with mode strings. Barely searchable. No staleness handling. The agent writes junk and it stays there forever.

OpenMemory sits between them. Storage is Markdown with YAML front matter — human-readable, git-friendly, trivial to inspect. Eight named tools instead of one memory({ mode: "something" }) monolith. Stale memories get flagged by comparing git hashes, expiration dates, and age. Global writes require user permission. Session memories clean up after themselves.

The design principle: the filesystem is the database. No moving parts.

Add to ~/.config/opencode/opencode.json:

{
  "plugin": ["@wszqkzqk/openmemory"],
  "permission": {
    "skill": { "openmemory": "allow" }
  }
}

git clone https://github.com/wszqkzqk/openmemory
cd openmemory
bun install
bun run build

Then copy into your global config:

cp dist/index.js ~/.config/opencode/plugins/openmemory.js
cp -r skills/openmemory ~/.config/opencode/skills/

Directories are created on first use. No config file required.

Once installed, the agent handles the rest. It browses the memory list before starting work, reads what's relevant, and records important discoveries without being asked. When a memory goes stale — a dependency upgrades, an API changes, you switch patterns — memory_check surfaces it. Bad information doesn't linger.

Global memory requires your permission. "Remember that I always use TypeScript strict mode" — the agent asks, you approve. Every future session sees it.

~/.local/share/openmemory/       # global — cross-project, your preferences
    python-style.md
    how-to-write-vala.md

project/.openmemory/
    session/ses_abc123/          # session — scratchpad, dies with the tab
        nasty-bug.md
    project/                     # project — stuff other sessions need
        why-we-ditched-grpc.md
        test-conventions.md

The agent is smart about scope. It puts temporary debugging notes in session, architectural decisions in project, and only touches global when you explicitly say "remember that I prefer..."

Every memory is a Markdown file with YAML front matter. The agent sees the filename and front matter first and decides whether to read the body. No wasted tokens loading irrelevant context.

---
title: Switched auth from JWT to session tokens
type: context
scope: project:backend
tags: [auth, security, redis]
created: 2026-05-01
updated: 2026-05-05
status: active
importance: 4
git-hash: 3f7c8a9b1d2e4f6a8b0c1d3e5f7a9b2c4d6e8f0a
---

JWT invalidation was getting out of hand. Moved to Redis-backed sessions
with express-session + connect-redis. Server-side revocation, no more
scattered refresh tokens.

Middleware: src/middleware/auth.ts
Config:     src/config/session.ts

The git-hash records the full commit SHA-1 at the time the memory was written. When HEAD moves past that commit, memory_check flags it — the content might have drifted.

The design is agent-agnostic. Any coding tool that can read and write files can use this structure. OpenCode got the first plugin implementation; others are just a matter of wiring up the same eight tools to a different runtime.

A companion skill teaches the agent when to read and when to write. It learns to check memory before starting work and to save important discoveries after. You don't have to remind it.

When a session compacts, the agent gets a fresh system prompt. Without intervention, all its accumulated project knowledge evaporates.

OpenMemory hooks into the compaction lifecycle and injects a summary of active project memories plus any session discoveries. The compacted session wakes up knowing what the project looks like. This kind of detail is what separates "works in the demo" from "works at 4am when you're debugging a production incident."

Optional overrides:

{
  "openmemory": {
    "globalPath": "~/.local/share/openmemory",
    "staleAgeDays": 60,
    "maxInjectTokens": 2000
  }
}

git clone https://github.com/wszqkzqk/openmemory
cd openmemory
bun install
bun test        # 56 tests, 7 suites
bun run build   # → dist/index.js

The full design document is in DESIGN.md — architecture rationale, research against 11 competing plugins, and verified API details.

GPL-3.0-or-later. See LICENSE.