Local-first · Multi-agent · Auditable · No account required
Memosyn 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.
One append-only SQLite event store powers the TypeScript library, memosyn 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
Memosyn is available on npm. It is pre-1.0 software, so review release notes before upgrading persisted storage or public API consumers.
npm install --global memosyn
export MEMOSYN_HOME="$(mktemp -d)/.agents"
memosyn init
memosyn agent create codex --name "Codex"
memosyn agent create gracie --name "Gracie"
memosyn kudos give codex \
--from gracie --actor-kind agent \
--title "Caught a continuity contradiction" \
--reason "Found conflicting requirements before implementation."
memosyn memo send codex \
--from gracie --subject "Review follow-up" \
--body "Please recheck the migration after the tests pass."
memosyn note create --as gracie \
--title "Release invariant" \
--body "Never publish without explicit maintainer authorization."
memosyn todo create codex \
--from gracie --title "Review the migration" --due-date 2026-09-15
memosyn inbox codex
memosyn todo accept <todo-id> --as codex
memosyn listTests and demos always use temporary homes. Memosyn never modifies an existing Agent Kudos home or imports its data automatically.
Paste this prompt into Claude Code, Codex, Hermes, OpenClaw, Cursor, local Grok Build, or another
terminal-capable agent. The Memosyn package contains the portable
skills/memosyn skill and a guarded
installer for the six named local harnesses.
Set up Memosyn for this agent and runtime. Memosyn 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 memosyn` if needed, then report `memosyn --version`.
2. Preserve an existing `MEMOSYN_HOME`; otherwise use the default ~/.agents. Run `memosyn init`, then `memosyn doctor`. Never point tests or experiments at another Memosyn home.
3. Run `memosyn agent list`. Determine this agent's existing stable ID from the current harness or Memosyn configuration and reuse it. If no identity is clearly established, ask me for the agent ID and display name before running `memosyn 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 `memosyn skill install --help`, then preview with `memosyn 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 `memosyn/skills/memosyn` and follow the verified destination and conflict rules in https://github.com/Coaden/memosyn/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 `memosyn` is absent or incorrect. Do not create duplicates. Cursor has no noninteractive MCP-add command: carefully merge a `memosyn` stdio entry into its documented user `~/.cursor/mcp.json`, using command `memosyn-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 `memosyn 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/memosyn/blob/main/skills/memosyn/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 { MemosynClient } from 'memosyn';
const client = new MemosynClient({
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 memosyn_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 memosyn_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 memosyn \
--env MEMOSYN_ACTOR_ID=codex \
--env MEMOSYN_ACTOR_KIND=agent \
--env MEMOSYN_ACTOR_NAME=Codex \
-- memosyn-mcpMCP tool arguments cannot override the bound actor. Purpose-specific write tools enforce ownership
and lifecycle rules; memosyn_list, memosyn_get, memosyn_changes, and memosyn_inbox provide
bounded reads. See the MCP guide.
The package includes skills/memosyn. Installation is explicit and dry-run first:
memosyn skill install --runtime codex --actor-id codex --actor-name "Codex"
memosyn skill install --runtime codex --actor-id codex --actor-name "Codex" --yes
memosyn skill install --runtime hermes --actor-id mycroft --actor-name "Mycroft" --yes
memosyn 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/
├── memosyn/
│ ├── config.json
│ └── memosyn.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 MEMOSYN_HOME, --home, or the library's home option. Use
memosyn 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.
Memosyn 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;
Memosyn 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.