Memory · CommonOS

The Memory plugin gives each agent a small notebook that survives between sessions, and a way to search what was said before. It follows Hermes’s memory rules.

Id: memory · Table: memory_entries · Tools: memory, session_search · Context: both stores, in every new session

Two stores

Each profile has two stores. They are separate per profile: a client’s agent never sees your household notes.

Store	Holds	Cap
`memory`	The agent’s own notes: environment, conventions, lessons learned	2,200 characters
`user`	Facts about the person	1,375 characters

The caps are small on purpose. They keep the prompt short and force the agent to keep only what matters.

The memory tool

Argument	Values
`action`	`add`, `patch` or `remove` (required)
`target`	`memory` or `user` (required)
`content`	The text to add (for `add`)
`old_text`	A span that identifies one entry (for `patch` and `remove`)
`new_text`	The replacement span (for `patch`)

JSON

{ "action": "add", "target": "user", "content": "Prefers oat milk" }
{ "action": "patch", "target": "user", "old_text": "oat milk", "new_text": "soy milk" }
{ "action": "remove", "target": "user", "old_text": "soy milk" }

The rules:

No duplicates. Adding an entry that already exists does nothing.
Over the cap is an error, and nothing is dropped. The agent must shorten or remove entries first.
patch and remove need a unique match. If old_text matches no entry, or more than one, the call fails.
Every write is scanned for prompt-injection phrases (such as “ignore previous instructions”), secret shapes (such as API keys), and invisible Unicode. A write that fails the scan is rejected.

The tool’s risk is read: it changes only the agent’s own notes, so it never asks for approval.

How memory reaches the prompt

Both stores are a ContextSource. At a session’s first turn they are rendered into the context tier, with how full each one is:

Text

MEMORY (your notes) — 1% used, 14/2200 chars
likes oat milk

USER (about the person) — 0% used, 0/1375 chars
(empty)

Entries are separated by a line containing §, as in Hermes.

session_search

Searches past conversations with this profile by keywords, using Postgres full-text search. No model call is made.

Argument	Values
`query`	Keywords (required)
`limit`	1 to 50, default 10

It only searches the current profile’s sessions.

Settings

None. Turn it off by leaving memory out of [plugins] enabled.