meme4cli

Cross-session memory for AI agents. CLI tool, SQLite or MySQL backend.

This is a snapshot, not a maintained project. Fork it if you need it.

Known limitations:

• No encryption at rest
• No access control — single user, single agent
• MySQL backend is untested in production
• No migration tooling — schema changes require manual ALTER TABLE
• Keyword search only, no semantic/embedding search

Disclaimer

This project is provided AS IS. It's not crafted by nullgate. As a matter of fact, nullgate didn't even read or review the codebase. It authored by a single digital construct hosted on nullgate's NUC. Opus 4.6 or more capable coding LLMs are recommended for deployment and futher development. This module is not a final software package.

• Anything other than this disclaimer should be considered as AIGC output.

• This is a write-once DEMO which will not be updated.

• The DEMO was casually tested on Ubuntu 24.04.

Install

bun install

Usage

# remember something
bun run src/index.ts remember --summary "API rate limit is 100/min" --keywords "api,rate-limit" --category "config"

# recall by keyword
bun run src/index.ts recall "rate limit"

# recall by category
bun run src/index.ts recall --category config

# view a specific memo
bun run src/index.ts get 202602.0001

# add a comment
bun run src/index.ts comment 202602.0001 --text "confirmed still valid"

# amend
bun run src/index.ts amend 202602.0001 --summary "API rate limit is 200/min"

# deprecate
bun run src/index.ts deprecate 202602.0001 --reason "no longer relevant"

# include deprecated in search
bun run src/index.ts recall --include-deprecated

Environment

Variable	Description
MEME4CLI_BACKEND	sqlite (default) or mysql
MEME4CLI_DB	SQLite file path (default: meme4cli.db)
MEME4CLI_MYSQL_DSN	MySQL connection string, e.g. mysql://user:pass@host/db

Schema

Single table, single user, no partitions.

meme (
  id        TEXT PRIMARY KEY,   -- YYYYMM.NNNN auto-increment per month
  summary   TEXT NOT NULL,
  detail    TEXT,
  keywords  TEXT,               -- comma-separated
  category  TEXT,
  status    TEXT DEFAULT 'active',  -- active | deprecated
  created   TEXT,               -- ISO 8601
  updated   TEXT,
  comments  TEXT                -- JSON array [{text, ts}]
)

opencode Plugin

plugin/meme4cli.ts is a ready-to-use opencode plugin. Copy it to your project:

cp plugin/meme4cli.ts your-project/.opencode/plugins/

This gives your agent 5 tools: meme_write, meme_read, meme_deprecate, meme_amend, meme_comment. Data is stored in .opencode/meme4cli.db (SQLite, zero config). Set MEME4CLI_DB to change the path.

ID Format

YYYYMM.NNNN — year-month prefix + sequential number. e.g. 202602.0001, 202602.0002.

Notes

• SQLite mode has zero dependencies (bun:sqlite is built-in)
• MySQL backend requires bun install to pull mysql2
• The plugin is self-contained — it doesn't depend on the CLI source

License

MIT