synomem 0.1.0

package/AGENTS.md

@@ -0,0 +1,42 @@
+# AGENTS.md
+
+This repository is a public TypeScript package. Changes should be reviewable, portable, secure by default, and appropriate for an OSS audience.
+
+## Working agreement
+
+- Read `ARCHITECTURE.md`, `SECURITY.md`, and the local `.docs/plan.md` when present before architectural changes.
+- Use Node.js 22.13 or newer, ESM, strict TypeScript, and the built-in `node:sqlite` API.
+- Keep V1 single-machine and local-first. Do not add hosted services, telemetry, accounts, network listeners, or postinstall behavior.
+- Do not publish packages, create releases, alter npm configuration, or write into a user’s real `~/.agents` directory without explicit authorization.
+- Tests and demos must use isolated temporary homes.
+- Never commit real Synomem data, SQLite databases, environment files, secrets, generated coverage, or npm tarballs.
+
+## Architectural invariants
+
+- SQLite event rows are canonical and append-only. State changes are new events.
+- Agent IDs are validated stable identities; aliases never silently merge identities.
+- MCP writes use the actor bound at server startup. Tool arguments cannot override it.
+- `WINS.md`, inbox files, and `profile.json` are generated projections. `NOTES.md` is human-owned and must never be overwritten.
+- Machine reads stay context-bounded: compact list/change feeds have conservative defaults, hard limits, byte budgets, and opaque cursors. `WINS.md` is not a machine query source.
+- Projection cleanup may remove only regular files listed in the generated-files manifest.
+- Normal mutations must not rebuild or rewrite every pending inbox entry; full regeneration belongs to the explicit rebuild operation.
+- `system` actors are automation identities and have no implicit agent or administrative authority.
+- Raw JSON/JSONL export must remain available when canonical rows are unsupported or malformed; writes must fail closed across unknown event semantics.
+- Do not follow symlinks outside the configured home.
+- Evidence is descriptive metadata, never captured tool output or secret material.
+- No filesystem work occurs at module import time, and library code never calls `process.exit()`.
+
+## Quality gates
+
+Run these before handing work off:
+
+```bash
+npm run format:check
+npm run lint
+npm run typecheck
+npm test
+npm run test:coverage
+npm run pack:check
+```
+
+Update documentation and `CHANGELOG.md` when behavior, commands, policy, storage, or public types change. Add tests for security boundaries and observable behavior, not merely implementation details.

package/ARCHITECTURE.md

@@ -0,0 +1,126 @@
+# Architecture
+
+Synomem is one ESM package with four adapters over a shared asynchronous domain-service port:
+
+```text
+TypeScript library ─┐                         ┌─> SynomemClient ─> SynomemStorage ─> SQLite events
+CLI                ─┼─> configured factory ──┤                                       ├─> indexes
+stdio MCP          ─┘                         └─> RemoteSynomemService ─> HTTPS API    └─> files
+```
+
+A single package keeps validation, policy, migrations, types, CLI behavior, and MCP behavior
+consistent. Public operations are asynchronous. CLI and MCP receive the service through an
+injectable factory and do not reach into concrete storage or projection objects. SQLite remains
+behind the local service so a later hosted transport can preserve domain semantics without exposing
+database APIs remotely.
+
+## Domain model
+
+One workspace contains stable agent identities and four record aggregates:
+
+- Kudos: given, acknowledged, or revoked recognition.
+- Memos: sent, read, or archived one-to-one messages, including self-memos.
+- Notes: owner-scoped knowledge with optimistic revisions and archive state.
+- Todos: assigned actions with updates, completion, reopening, and cancellation.
+
+Every mutation appends a versioned event with a workspace ID, aggregate ID, aggregate version,
+actor, timestamp, optional actor-scoped idempotency key, source, and metadata. The store assigns a
+monotonic ingestion sequence inside the write transaction. Historical rows are never updated or
+deleted to represent state changes.
+
+SQLite schema version 3 adds the generalized event envelope and `items_current`. Existing kudos
+events remain valid through deterministic legacy normalization. Unsupported or malformed semantics
+make writes and rebuilds fail closed while raw JSON and JSONL export remains available.
+
+## Query models
+
+`events` is canonical. `agents`, `aliases`, `kudos_current`, and `items_current` are transactional,
+rebuildable query indexes. `items_current` stores only bounded summary fields and participant IDs;
+full bodies, reasons, evidence, descriptions, source data, and metadata stay in canonical events.
+
+List reads default to 10 records and allow at most 50. Change reads default to 20 and allow at most 100. Both use opaque sequence cursors and an approximate 24 KiB item-data budget. Detail reads
+reconstruct one requested aggregate. Generated Markdown is never a machine query source.
+
+## Authorization
+
+MCP servers bind one actor at startup, and tool inputs cannot override it. Humans have local
+administrative authority. Agents can manage their own notes, recipient memo state, and todos they
+created or received. System actors have no implicit agent or administrator authority. Actor
+principals are keyed by both kind and ID; matching text IDs across kinds do not share author access.
+
+Delivery and ownership are distinct from visibility. Direct participants can access their record;
+`workspace` grants other workspace actors access; `public` makes a record eligible for public export.
+The filesystem owner remains the ultimate local authority.
+
+## Concurrency and durability
+
+SQLite uses WAL, foreign keys, `synchronous=FULL`, a bounded busy handler, and `BEGIN IMMEDIATE`
+transactions. Actor-scoped idempotency protects retries. Note and todo revisions use aggregate
+versions so stale writes fail with `REVISION_CONFLICT` rather than overwriting concurrent state.
+
+V1 supports one machine and one filesystem owner. A future hosted service must enforce the same
+policies server-side and add authentication, tenant isolation, transport security, conflict handling,
+availability, and explicit data migration.
+
+## Projections
+
+Normal mutations synchronize only affected agents. `rebuild` recreates all derived indexes and
+files. `WINS.md`, `MEMORY.md`, `TODOS.md`, inbox entries, and `profile.json` are generated.
+`NOTES.md` is human-owned and never overwritten or added to the generated-files manifest.
+
+Cleanup removes only manifest-listed regular files beneath the configured home and never follows
+symlinks. Projection timestamps derive from canonical event time for deterministic rebuilds.
+
+## Module boundaries
+
+- `src/types.ts`: public types and event contracts.
+- `src/schemas.ts`: runtime validation and payload limits.
+- `src/storage.ts`: SQLite ownership, migrations, indexes, transactions, backups, and raw recovery.
+- `src/client.ts`: public domain API, policy, lifecycle, and aggregate reconstruction.
+- `src/service.ts`: transport-neutral asynchronous service, capability, and factory contracts.
+- `src/ports/`: repository and projection contracts injected into the authoritative core.
+- `src/import.ts`: consistent local snapshot, bounded canonical bundle, and remote import client.
+- `src/oauth.ts` and `src/credentials.ts`: PKCE login/refresh and OS credential-store boundary.
+- `src/projections.ts`: deterministic safe filesystem views.
+- `src/cli.ts`: command parsing, human/JSON output, and stable exit codes.
+- `src/mcp/index.ts`: actor binding, tools, resources, prompts, and visibility enforcement.
+- `src/skill-install.ts`: explicit constrained skill placement.
+
+## Future boundary
+
+`SynomemCore` receives repository and projection ports; `SynomemClient` composes it with the local
+SQLite and filesystem implementations and retains local administration. The current storage class
+is not a public API contract. Adapters use explicit service capabilities and administrative methods
+instead of accessing it. A hosted implementation should expose domain operations through an
+authenticated service, not connect clients directly to a remote database or synchronize SQLite
+files.
+
+Repository operations are async-capable even though SQLite executes its statements synchronously.
+The local adapter serializes asynchronous domain transactions on each connection and keeps a
+separate synchronous transaction primitive for migrations and local projection maintenance. This
+lets a remote implementation hold a transaction across awaited driver calls without changing
+domain behavior or allowing overlapping transactions on one SQLite connection.
+
+`RemoteSynomemService` is the client-side implementation of the same service contract. It calls the
+versioned domain API described by `openapi/synomem-v1.yaml`, sends credentials only in the
+authorization header, moves retry keys to `Idempotency-Key`, and never sends actor identity as
+authority. It does not connect to Postgres or create local projections.
+
+Configuration schema version 3 makes backend selection explicit. Existing schema version 2 files
+migrate to `{ "kind": "local" }`; remote selection records only the service origin and workspace
+identifier. Credentials are never stored in `config.json`. `SynomemClient` remains intentionally
+local-only and refuses a remote backend before creating or opening SQLite; adapter factories are
+responsible for selecting `RemoteSynomemService`. The CLI and stdio MCP use that configured factory
+by default, so remote mode performs no SQLite or filesystem projection writes.
+
+Remote credentials are indexed by service origin, workspace, and stable `(kind,id)` actor identity;
+display-name changes do not orphan them. The environment token takes precedence without
+persistence. Interactive authorization uses protected-resource and authorization-server discovery,
+PKCE S256, a fixed registered loopback callback, and OS credential storage. Refresh tokens never
+enter Synomem configuration or events.
+
+Local-to-remote import is deliberately not synchronization. The client creates a consistent,
+checksummed SQLite snapshot bundle, previews it against an explicit destination, and submits it only
+after confirmation. The remote service owns authorization, plan signing, empty-target enforcement,
+validation, and transactional ingestion. The local source and backend configuration remain
+unchanged.

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes will be documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and releases follow Semantic Versioning.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-04
+
+### Added
+
+- Four distinct event-sourced domains: kudos, one-recipient memos, owner-private notes, and todos.
+- Consent-based cross-agent todo assignment with explicit acceptance and rejection.
+- Unified, context-bounded item and change feeds with opaque sequence watermarks.
+- Persistent workspace and agent identities, actor-scoped idempotency, and optimistic revisions.
+- Local-first SQLite storage with append-only canonical events and rebuildable projections.
+- TypeScript library, `synomem` CLI, actor-bound `synomem-mcp` stdio server, and portable agent skill.
+- Explicit local and remote backend configuration through a shared asynchronous domain-service
+  boundary.
+- OAuth authorization-code PKCE, OS credential storage, and an HTTPS remote service client.
+- Previewed, checksummed local-to-remote import without implicit synchronization.
+- Public OpenAPI contract for independently operated hosted services.
+
+### Security
+
+- MCP mutations cannot override the actor bound at server startup.
+- Notes remain owner-private, and direct-record authorization distinguishes actor kind and ID.
+- Machine-facing reads enforce hard item limits, byte budgets, and opaque cursors.
+- Unknown canonical semantics fail writes closed while raw JSON and JSONL recovery remain available.
+- Remote credentials remain outside configuration, events, command arguments, and normal output.
+- Skill installation is explicit, constrained to supported runtime directories, and dry-run by
+  default.
+
+[Unreleased]: https://github.com/Coaden/synomem/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Coaden/synomem/releases/tag/v0.1.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,29 @@
+# Code of Conduct
+
+## Our standard
+
+Synomem is committed to a welcoming, respectful, and harassment-free community. We value technical rigor, curiosity, kindness, clear feedback, and recognition grounded in real contributions.
+
+Examples of positive behavior include:
+
+- showing empathy and respect for different experiences and viewpoints;
+- giving and accepting constructive technical feedback;
+- focusing criticism on ideas and code rather than people;
+- acknowledging contributions accurately;
+- taking responsibility, apologizing, and repairing harm.
+
+Unacceptable behavior includes harassment, discrimination, threats, sexualized attention, personal attacks, deliberate intimidation, doxxing, publishing private information, sustained disruption, or retaliation against someone who reports a concern.
+
+## Scope
+
+This policy applies in project spaces and when someone publicly represents the project, including repositories, issues, pull requests, discussions, community events, and project-related private communication.
+
+## Enforcement
+
+Report conduct concerns privately to the repository maintainers through GitHub. Maintainers will review reports promptly, protect reporter privacy as practical, and respond proportionally. Possible actions include a private correction, warning, temporary restriction, removal of content, or permanent exclusion from project spaces.
+
+Maintainers must disclose conflicts of interest and recuse themselves when appropriate. Good-faith reports will not result in retaliation.
+
+## Attribution
+
+This policy is inspired by the Contributor Covenant and common open-source community standards. It may be refined as the community grows.

package/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing to Synomem
+
+Thank you for helping make durable agent coordination more useful—and slightly more robotic.
+
+## Before opening a change
+
+For substantial features, open an issue first so scope and storage compatibility can be discussed. Security reports belong in GitHub private vulnerability reporting, not public issues.
+
+By participating, you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Development setup
+
+```bash
+git clone https://github.com/Coaden/synomem.git
+cd synomem
+npm install
+npm test
+```
+
+Node.js 22.13 or newer is required. The project uses ESM, strict TypeScript, Node’s built-in SQLite module, Vitest, ESLint, and Prettier.
+
+## Pull requests
+
+1. Create a focused branch from `main`.
+2. Add or update tests for observable behavior and security boundaries.
+3. Update documentation and `CHANGELOG.md` when public behavior changes.
+4. Run every quality gate:
+
+   ```bash
+   npm run format:check
+   npm run lint
+   npm run typecheck
+   npm test
+   npm run test:coverage
+   npm run pack:check
+   ```
+
+5. Explain the motivation, implementation, tests, and storage or security impact in the pull request.
+
+Keep commits reviewable. Do not commit real Synomem homes, databases, secrets, build output, coverage, or tarballs.
+
+## Design expectations
+
+Preserve the invariants in [AGENTS.md](AGENTS.md) and [ARCHITECTURE.md](ARCHITECTURE.md). New event types require validation, migration consideration, query/projection behavior, protocol tests, documentation, and export coverage.
+
+## Releases
+
+Maintainers follow [docs/releasing.md](docs/releasing.md). Ordinary CI never publishes packages. Publishing requires an intentional GitHub Release and an npm trusted-publisher relationship.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Troy Locke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+<div align="center">
+
+# Synomem
+
+### Shared Memory for Agents
+
+**Local-first · Multi-agent · Auditable · No account required**
+
+[![CI](https://github.com/Coaden/synomem/actions/workflows/ci.yml/badge.svg)](https://github.com/Coaden/synomem/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/synomem.svg)](https://www.npmjs.com/package/synomem)
+[![Node.js 22.13+](https://img.shields.io/badge/Node.js-22.13%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![MCP](https://img.shields.io/badge/MCP-stdio-6f42c1)](https://modelcontextprotocol.io/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+[CLI reference](docs/cli.md) · [MCP guide](docs/mcp.md) · [Storage](docs/storage-format.md) · [Security](SECURITY.md)
+
+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](docs/cli.md#backend-and-authentication).
+
+</div>
+
+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.
+
+## Core philosophy
+
+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]
+> The renamed `synomem` package has not been published yet. It is pre-1.0 software, so review the
+> release notes and rename guidance before upgrading persisted storage or public API consumers.
+
+## Quick start
+
+```bash
+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 list
+```
+
+Tests and demos always use temporary homes and never modify an existing configured home.
+
+## Let your agent set it up
+
+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`](https://github.com/Coaden/synomem/tree/main/skills/synomem) skill and a guarded
+installer for the six named local harnesses.
+
+```text
+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.
+```
+
+## TypeScript API
+
+```ts
+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.
+
+## Context-safe reads
+
+`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.
+
+## MCP
+
+Every runtime launches the same stdio server with its own fixed actor identity while sharing one
+local home:
+
+```bash
+codex mcp add synomem \
+  --env SYNOMEM_ACTOR_ID=codex \
+  --env SYNOMEM_ACTOR_KIND=agent \
+  --env SYNOMEM_ACTOR_NAME=Codex \
+  -- synomem-mcp
+```
+
+MCP 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](docs/mcp.md).
+
+## Agent skill
+
+The package includes [`skills/synomem`](skills/synomem). Installation is explicit and dry-run first:
+
+```bash
+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 status
+```
+
+No 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`.
+
+## Storage
+
+```text
+~/.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.
+
+## Trust and privacy
+
+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](SECURITY.md) before sharing exports.
+
+## Future hosted direction
+
+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.
+
+## Development
+
+```bash
+npm ci
+npm run format:check
+npm run lint
+npm run typecheck
+npm test
+npm run test:coverage
+npm run pack:check
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/releasing.md](docs/releasing.md). Do not publish or
+create releases without explicit maintainer authorization.
+
+## License
+
+MIT © Troy Locke. See [LICENSE](LICENSE).