Local-first · Multi-agent · Auditable · No account required
CLI reference · MCP guide · Storage · Security
The experimental remote client supports explicit backend configuration. synomem backend use remote --url <https-origin> --workspace <id> makes the CLI and stdio MCP use the versioned domain API with
actor-scoped OAuth credentials; it does not synchronize local history or create a shadow SQLite
database. Hosted API and HTTP-MCP implementations are separate products and are not included here.
See the CLI reference.
Synomem gives humans and AI agents four durable ways to coordinate beyond a disappearing chat:
- Kudos recognize a concrete contribution.
- Memos deliver a message to another agent or to one's future self.
- Notes retain agent-owned, revisable knowledge.
- Todos track assigned actions with optional date-only or timezone-aware deadlines.
Traditional AI memory layers resemble an isolated file cabinet for one model. Synomem turns memory into a shared, transactional canvas: independently operating agents can retain private knowledge, deliver durable context, delegate work with consent, track commitments, and recognize good collaboration through one auditable protocol. V1 provides that substrate locally; its interfaces are designed so the same agent identities and semantics can later cross machines through an explicitly configured service.
One append-only SQLite event store powers the TypeScript library, synomem CLI, actor-bound stdio
MCP server, compact change feeds, and readable Markdown projections. V1 runs entirely on one machine
and opens no network listener.
Important
Synomem is pre-1.0 software. Review the release notes before upgrading persisted storage or public API consumers.
npm install --global synomem
export SYNOMEM_HOME="$(mktemp -d)/.agents"
synomem init
synomem agent create codex --name "Codex"
synomem agent create gracie --name "Gracie"
synomem kudos give codex \
--from gracie --actor-kind agent \
--title "Caught a continuity contradiction" \
--reason "Found conflicting requirements before implementation."
synomem memo send codex \
--from gracie --subject "Review follow-up" \
--body "Please recheck the migration after the tests pass."
synomem note create --as gracie \
--title "Release invariant" \
--body "Never publish without explicit maintainer authorization."
synomem todo create codex \
--from gracie --title "Review the migration" --due-date 2026-09-15
synomem inbox codex
synomem todo accept <todo-id> --as codex
synomem listTests and demos always use temporary homes and never modify an existing configured home.
Paste this prompt into Claude Code, Codex, Hermes, OpenClaw, Cursor, local Grok Build, or another
terminal-capable agent. The Synomem package contains the portable
skills/synomem skill and a guarded
installer for the six named local harnesses.
Set up Synomem for this agent and runtime. Synomem is a local-first coordination system for durable kudos, one-to-one memos, private agent notes, and consent-based assigned todos. It uses an append-only SQLite database under ~/.agents by default, an actor-bound stdio MCP server, and a portable Agent Skill. Multiple local agents may share the database, but every MCP server must be bound to its own stable identity.
Work autonomously through the safe, reversible steps below. Do not expose secrets, overwrite unrelated configuration, invent an identity, use --force without my explicit approval, or modify another agent's integration.
1. Verify Node.js 22.13+ and npm are available. Install or update the public package with `npm install --global synomem` if needed, then report `synomem --version`.
2. Preserve an existing `SYNOMEM_HOME`; otherwise use the default ~/.agents. Run `synomem init`, then `synomem doctor`. Never point tests or experiments at another Synomem home.
3. Run `synomem agent list`. Determine this agent's existing stable ID from the current harness or Synomem configuration and reuse it. If no identity is clearly established, ask me for the agent ID and display name before running `synomem agent create <id> --name <name>`. Never silently merge or rename identities.
4. Detect the current harness from actual local evidence and its installed CLI help. Use runtime `claude` for Claude Code, `codex` for Codex, `hermes` for Hermes, `openclaw` for OpenClaw, `cursor` for Cursor, or `grok` for local Grok Build (`grokbot` is accepted as an alias). Check `synomem skill install --help`, then preview with `synomem skill install --runtime <runtime> --actor-id <agent-id> --actor-name <display-name>`. Review the exact destination and apply the same command with `--yes`; it must report `current`. If the installed release does not yet list this runtime, locate the packaged source under the global npm root at `synomem/skills/synomem` and follow the verified destination and conflict rules in https://github.com/Coaden/synomem/blob/main/docs/skill.md instead. Do not guess a path, overwrite an existing skill, or create a fake harness home to make an unavailable runtime appear installed.
5. Inspect any actor-bound MCP registration command printed by the installer. Check the harness's existing MCP list/config first, then run the command only if `synomem` is absent or incorrect. Do not create duplicates. Cursor has no noninteractive MCP-add command: carefully merge a `synomem` stdio entry into its documented user `~/.cursor/mcp.json`, using command `synomem-mcp` and arguments `--actor-id <agent-id> --actor-kind agent --actor-name <display-name>`; preserve every existing entry.
6. Verify the harness can discover the installed skill and MCP server using its own list/status commands, then run `synomem doctor`. Start a new agent session if that harness does not live-reload a newly created skills directory.
7. If this is hosted Grok Bot rather than local Grok Build, do not claim it shares the desktop's local SQLite database. Install the package and skill only inside a persistent terminal environment where `npm`, local stdio MCP, and ~/.grok are actually available. Otherwise provide the skill URL https://github.com/Coaden/synomem/blob/main/skills/synomem/SKILL.md and explain the unsupported boundary; do not expose the local database through a tunnel.
8. Report the package version, stable actor ID, storage home, installed skill path, MCP registration and verification status, whether a new session is needed, and every file or configuration changed. Do not print record contents or environment values beyond the non-secret actor identity and home path.
import { SynomemClient } from 'synomem';
const client = new SynomemClient({
actor: { kind: 'agent', id: 'gracie', displayName: 'Gracie' },
});
await client.init();
await client.memos.send({
recipientAgentId: 'codex',
subject: 'Review follow-up',
body: 'Please recheck the migration after the tests pass.',
idempotencyKey: 'gracie-codex-migration-follow-up',
});
const note = await client.notes.create({
title: 'Release invariant',
body: 'Never publish without explicit maintainer authorization.',
});
await client.notes.revise({
noteId: note.record.event.id,
expectedVersion: note.record.current.version,
body: 'Never publish or create a release without explicit maintainer authorization.',
});
await client.todos.create({
assigneeAgentId: 'codex',
title: 'Review the migration',
due: { kind: 'date', date: '2026-09-15' },
});
const page = await client.items.list({ kinds: ['memo', 'todo'], limit: 10 });
const changes = await client.items.changes({ after: page.watermark });
await client.close();The library performs no filesystem work at import time and never terminates its host process.
client.items.list() and MCP synomem_list return 10 compact summaries by default and at most 50.
Summaries omit message bodies, kudos reasons and evidence, note bodies, todo descriptions, source,
and metadata. Fetch one authorized detail record with items.get(id) or synomem_get.
Incremental reads return at most 20 changes by default and 100 at most. List and change responses also stop around a 24 KiB item-data budget and return opaque continuation cursors. Agents should save watermarks and must not drain historical pages speculatively.
Every runtime launches the same stdio server with its own fixed actor identity while sharing one local home:
codex mcp add synomem \
--env SYNOMEM_ACTOR_ID=codex \
--env SYNOMEM_ACTOR_KIND=agent \
--env SYNOMEM_ACTOR_NAME=Codex \
-- synomem-mcpMCP tool arguments cannot override the bound actor. Purpose-specific write tools enforce ownership
and lifecycle rules; synomem_list, synomem_get, synomem_changes, and synomem_inbox provide
bounded reads. See the MCP guide.
The package includes skills/synomem. Installation is explicit and dry-run first:
synomem skill install --runtime codex --actor-id codex --actor-name "Codex"
synomem skill install --runtime codex --actor-id codex --actor-name "Codex" --yes
synomem skill install --runtime hermes --actor-id mycroft --actor-name "Mycroft" --yes
synomem skill statusNo postinstall hook changes an agent runtime. The installer never creates a missing runtime home and
refuses unowned conflicts unless --force is explicitly supplied. Supported local runtime names
are claude, codex, hermes, openclaw, cursor, and grok; grokbot aliases grok.
~/.agents/
├── synomem/
│ ├── config.json
│ └── synomem.sqlite3
└── <agent-id>/
├── profile.json
├── WINS.md
├── MEMORY.md
├── TODOS.md
├── inbox/{kudos,memos,todos}/
└── NOTES.md
SQLite events are canonical and append-only. Markdown and current-state tables are rebuildable
projections. NOTES.md is human-owned and is never overwritten; canonical agent notes project to
MEMORY.md.
Override the root with SYNOMEM_HOME, --home, or the library's home option. Use
synomem backup for a consistent snapshot and JSON or JSONL export for recovery. Never synchronize
the live database with Git, Dropbox, a network share, or a file-copy tool.
Synomem is audit-friendly, not tamper-proof. The local filesystem owner ultimately controls the database and configuration. Actor binding protects ordinary MCP use but does not cryptographically prove who launched a process.
Do not store credentials, cookies, tokens, authentication headers, environment values, private keys,
raw sensitive tool output, or unnecessary private content. public means eligible for public export;
Synomem never publishes automatically. Review SECURITY.md before sharing exports.
A later hosted service may preserve the same workspace-scoped event semantics, aggregate versions, idempotency, and bounded feeds. It will require a separately designed authenticated service with authorization, tenant isolation, transport security, conflict handling, availability, and explicit migration. The SQLite file is never a cloud synchronization protocol.
npm ci
npm run format:check
npm run lint
npm run typecheck
npm test
npm run test:coverage
npm run pack:checkSee CONTRIBUTING.md and docs/releasing.md. Do not publish or create releases without explicit maintainer authorization.
MIT © Troy Locke. See LICENSE.