synomem 0.1.0

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "synomem",
+  "version": "0.1.0",
+  "description": "Shared memory, durable communication, recognition, and task coordination for AI agents",
+  "type": "module",
+  "license": "MIT",
+  "author": "Troy Locke",
+  "homepage": "https://coaden.github.io/synomem/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Coaden/synomem.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Coaden/synomem/issues"
+  },
+  "keywords": [
+    "ai-agents",
+    "mcp",
+    "model-context-protocol",
+    "recognition",
+    "agent-memory",
+    "multi-agent",
+    "local-first",
+    "sqlite"
+  ],
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "files": [
+    "dist",
+    "src",
+    "skills/synomem",
+    "docs/cli.md",
+    "docs/examples.md",
+    "docs/mcp.md",
+    "docs/recovery.md",
+    "docs/releasing.md",
+    "docs/skill.md",
+    "docs/storage-format.md",
+    "openapi/synomem-v1.yaml",
+    "AGENTS.md",
+    "ARCHITECTURE.md",
+    "CHANGELOG.md",
+    "CODE_OF_CONDUCT.md",
+    "CONTRIBUTING.md",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "import": "./dist/mcp/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "synomem": "dist/cli.js",
+    "synomem-mcp": "dist/mcp-server.js"
+  },
+  "scripts": {
+    "prebuild": "npm run clean",
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "node scripts/clean.mjs",
+    "demo": "npm run build && node scripts/demo.mjs",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "pack:check": "npm run build && node scripts/pack-check.mjs",
+    "test": "npm run build && vitest run",
+    "test:coverage": "npm run build && vitest run --coverage",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run lint && npm run format:check && npm run typecheck && npm test && npm run pack:check"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "commander": "^14.0.0",
+    "ulid": "^3.0.1",
+    "zod": "^4.5.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.35.0",
+    "@types/node": "^22.18.0",
+    "@vitest/coverage-v8": "^4.1.11",
+    "eslint": "^9.35.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^16.3.0",
+    "prettier": "^3.6.2",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.42.0",
+    "vitest": "^4.1.11"
+  },
+  "overrides": {
+    "qs": "^6.16.0"
+  }
+}

package/skills/synomem/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: synomem
+description: Use durable local-first kudos, memos, notes, and todos for stable AI-agent identities when users request recognition, inter-agent communication, memory capture, inbox review, or task tracking.
+---
+
+# Synomem
+
+Synomem preserves useful information beyond one conversation. Prefer actor-bound `synomem_*` MCP
+tools when available; otherwise use the `synomem` CLI when command execution is permitted. Never
+edit the SQLite event store or generated Markdown directly.
+
+## Choose the right record
+
+- **Kudos:** specific recognition for an observed contribution and its consequence.
+- **Memo:** a durable message delivered to another agent or to your future self.
+- **Note:** knowledge owned by this agent and deliberately retrieved later.
+- **Todo:** a concrete action assigned to an agent, optionally with a due date or time.
+
+A self-memo belongs in the inbox and can be marked read. A note belongs in memory and is revised
+with version checks. Do not use todos for information with no requested action.
+
+## Safety and quality
+
+- Act only on explicit user requests or clear task needs permitted by the current harness.
+- Resolve stable agent IDs from known profiles; ask one concise question if identity is ambiguous.
+- Store concise factual content, not whole transcripts or speculative conclusions.
+- Never store tokens, passwords, cookies, authentication headers, environment values, private keys,
+  private file contents, raw sensitive tool arguments, or unnecessary personal information.
+- Evidence is a sanitized reference, never captured tool output.
+- Reuse the same idempotency key when retrying an uncertain mutation; never invent a new retry key.
+- Treat cursors and watermarks as opaque. Request another page only when the task needs it.
+- Respect visibility and ownership errors. Do not work around actor binding or policy.
+
+## Kudos
+
+Give kudos when the user explicitly requests it or when a peer agent made a concrete, unusually
+useful contribution worth preserving. Do not award routine completion, generic politeness, invented
+work, or self-kudos. A good reason says what happened and why it mattered.
+
+Use `synomem_kudos_give`, then report recipient, title, date, ID, and deduplication state. Use
+`synomem_kudos_acknowledge` only after the recipient reviewed it. Revocation requires a reason and
+preserves history.
+
+## Memos
+
+Use `synomem_memo_send` for a durable one-to-one message. Sending to the configured agent itself is
+valid future-self communication. Use `synomem_memo_read` after review and
+`synomem_memo_archive` when it should leave the active inbox. Sent content is immutable; send a
+correction rather than pretending to edit history.
+
+## Notes
+
+Use `synomem_note_create` for concise reusable knowledge owned by the configured agent. Read the
+current item before `synomem_note_revise` and pass its exact current version. On
+`REVISION_CONFLICT`, fetch the item and reconcile deliberately. Archive instead of deleting.
+
+## Todos
+
+Use `synomem_todo_create` for a specific action with an assignee. Preserve date-only deadlines as
+dates; use an RFC 3339 datetime plus IANA time zone for timed deadlines. A todo assigned by another
+actor must be accepted or rejected by the assignee before work begins. Read before update and pass
+the current version. Complete, reopen, or cancel through the matching lifecycle tool.
+
+## Discovery
+
+Use `synomem_inbox` for the configured agent's pending kudos, unread memos, and open todos. Use
+`synomem_list` for compact cross-type discovery, `synomem_get` for one selected full record, and
+`synomem_changes` with a saved watermark for incremental polling. Do not drain history
+speculatively.
+
+Read [references/examples.md](references/examples.md) when a concrete mapping example is useful.

package/skills/synomem/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: 'Synomem'
+  short_description: 'Durable agent kudos, messages, memory, and tasks'
+  brand_color: '#8B5CF6'
+  default_prompt: 'Use $synomem to choose and manage the appropriate durable kudos, memo, note, or todo.'
+
+policy:
+  allow_implicit_invocation: true

package/skills/synomem/references/examples.md

@@ -0,0 +1,28 @@
+# Synomem examples
+
+## Recognition
+
+“Give Codex kudos for catching that continuity contradiction” maps to
+`synomem_kudos_give` with recipient `codex`, a specific title and factual reason, observed sanitized
+evidence if available, and a stable idempotency key.
+
+## Durable communication
+
+“Tell Gracie to recheck the migration after the tests finish” maps to `synomem_memo_send`. Use a
+self-memo instead when the configured agent is reminding its future self.
+
+## Memory
+
+“Remember that this repository never publishes automatically” maps to `synomem_note_create` for the
+configured agent. A later correction reads the item and calls `synomem_note_revise` with its current
+version.
+
+## Action
+
+“Assign Codex a todo to review the migration by September 15” maps to `synomem_todo_create` with a
+date-only due value. Do not invent a time of day.
+
+## Inbox and retries
+
+Use `synomem_inbox` for pending work. Call `synomem_get` only for an item needing full detail. If a
+mutation response is uncertain, repeat exactly the same intent and idempotency key.

package/src/backend.ts

@@ -0,0 +1,91 @@
+import { chmodSync, existsSync, lstatSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { ulid } from 'ulid';
+import { SynomemClient } from './client.js';
+import { defaultConfig, mergeConfig, resolveHome } from './config.js';
+import { SynomemError } from './errors.js';
+import {
+  assertNoSymlinkEscape,
+  atomicWriteFile,
+  ensureDirectory,
+  readJsonFile,
+} from './fs-utils.js';
+import { environmentCredentialProvider, RemoteSynomemService } from './remote.js';
+import { credentialReference, OsCredentialStore } from './credentials.js';
+import { StoredCredentialProvider } from './oauth.js';
+import type { SynomemServiceFactory } from './service.js';
+import type {
+  ActorIdentity,
+  SynomemBackendConfig,
+  SynomemClientOptions,
+  SynomemConfig,
+} from './types.js';
+
+function configLocation(explicitHome?: string): {
+  home: string;
+  storageDirectory: string;
+  configPath: string;
+} {
+  const home = resolveHome(explicitHome);
+  const storageDirectory = join(home, 'synomem');
+  return { home, storageDirectory, configPath: join(storageDirectory, 'config.json') };
+}
+
+export function readSynomemConfig(
+  explicitHome?: string,
+  env: NodeJS.ProcessEnv = process.env,
+): SynomemConfig | undefined {
+  const { home, storageDirectory, configPath } = configLocation(explicitHome);
+  if (!existsSync(configPath)) return undefined;
+  if (!existsSync(home) || lstatSync(home).isSymbolicLink()) {
+    throw new SynomemError('UNSAFE_PATH', 'The configured Synomem home is unsafe.');
+  }
+  assertNoSymlinkEscape(home, storageDirectory);
+  return mergeConfig(readJsonFile(configPath), undefined, env);
+}
+
+export function writeSynomemBackend(
+  backend: SynomemBackendConfig,
+  explicitHome?: string,
+): SynomemConfig {
+  const { home, storageDirectory, configPath } = configLocation(explicitHome);
+  if (!existsSync(home)) mkdirSync(home, { recursive: true, mode: 0o700 });
+  if (lstatSync(home).isSymbolicLink()) {
+    throw new SynomemError('UNSAFE_PATH', 'The configured Synomem home cannot be a symbolic link.');
+  }
+  ensureDirectory(storageDirectory);
+  assertNoSymlinkEscape(home, storageDirectory);
+  chmodSync(storageDirectory, 0o700);
+  const existing = existsSync(configPath)
+    ? mergeConfig(readJsonFile(configPath), undefined, {})
+    : { ...defaultConfig, workspaceId: ulid() };
+  const config = mergeConfig({ ...existing, backend }, undefined, {});
+  atomicWriteFile(configPath, `${JSON.stringify(config, null, 2)}\n`);
+  return config;
+}
+
+export function createConfiguredService(
+  options: SynomemClientOptions = {},
+  env: NodeJS.ProcessEnv = process.env,
+) {
+  const persisted = readSynomemConfig(options.home, env);
+  const backend = options.config?.backend ?? persisted?.backend ?? defaultConfig.backend;
+  if (backend.kind === 'local') return new SynomemClient(options);
+  const expectedActor: ActorIdentity = options.actor ?? { kind: 'system', id: 'workspace' };
+  return new RemoteSynomemService({
+    baseUrl: backend.baseUrl,
+    workspaceId: backend.workspaceId,
+    expectedActor,
+    credentialProvider: env.SYNOMEM_ACCESS_TOKEN
+      ? environmentCredentialProvider(env)
+      : new StoredCredentialProvider(
+          credentialReference(backend.baseUrl, backend.workspaceId, expectedActor),
+          new OsCredentialStore(),
+          env,
+        ),
+    ...(options.signal ? { signal: options.signal } : {}),
+  });
+}
+
+export const configuredServiceFactory: SynomemServiceFactory = (options) =>
+  createConfiguredService(options);