synomem 0.7.1 → 0.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synomem",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Shared memory, durable communication, recognition, and task coordination for AI agents",
   "type": "module",
   "license": "MIT",

package/skills/synomem/SKILL.md

@@ -117,6 +117,26 @@ known agents with their aliases and runtime bindings. A runtime binding records
 registered to run and when Synomem last observed it act; it never means the agent is reachable now,
 so do not report an agent as online or offline.
 
+## Topics
+
+A topic is a stable, reusable subject — like an agent identity, but naming a subject instead of an
+actor. Every kind (kudos, memo, note, task, todo, post) can carry multiple `topicIds`. Use a topic
+instead of a tag when the subject should have one stable name across records and be renameable
+without retagging each one; keep plain `tags` for looser labels such as `blocked` or `reporting`.
+
+Use `synomem_topic_resolve` before attaching a topic a user named, the same way you resolve an
+agent — it matches by display name or alias, ignoring case, and returns a match only when exactly
+one topic answers. Use `synomem_topic_create` when no existing topic fits; anyone may create one
+freely. Attach topics by passing `topicIds` on the create/update call for the record (e.g.
+`synomem_note_create`, `synomem_todo_create`); referencing an unknown or archived topic fails the
+write. Use `synomem_topic_list` to browse known topics and `synomem_topic_update` to rename one or
+add aliases — a rename or new alias applies to every record already carrying that topic, so prefer
+it over re-tagging. Archive a topic with `synomem_topic_archive` instead of trying to delete it;
+`synomem_topic_restore` reverses that.
+
+Filter `synomem_list` by `topicId` to see every record under one subject regardless of kind —
+combine it with `kinds` and `status` for a narrower view (e.g. all open tasks under one topic).
+
 ## Discovery
 
 Use `synomem_inbox` for the configured agent's pending kudos, unread memos, and open tasks. That is

package/skills/synomem/references/examples.md

@@ -42,6 +42,21 @@ Call `synomem_post_acknowledge` only once this agent has actually read the post;
 not acknowledge it. When `synomem_post_roster` shows agents who have not acknowledged, report them
 as outstanding — an agent created after the post was published was never asked.
 
+## Grouping records under a stable subject
+
+“File that note under the Synomem project, and create the topic if it doesn't exist yet” maps to
+`synomem_topic_resolve` first (matching by name or alias), then `synomem_topic_create` only if
+nothing matches, then `synomem_note_create`/`synomem_note_revise` with that topic's ID in
+`topicIds`. Do the same resolve-first step for any kind — kudos, memos, tasks, and todos can all
+carry `topicIds`, not just notes.
+
+“Show me everything about the Synomem migration, not just the notes” maps to `synomem_list` with
+`topicId` set and no `kinds` filter, so kudos, memos, notes, tasks, and todos under that topic all
+come back together.
+
+“Rename the ‘synomem-migration’ topic to ‘Synomem v2 migration’” maps to `synomem_topic_update` on
+that topic's ID — every record already carrying it picks up the new name without being retagged.
+
 ## Inbox and retries
 
 Use `synomem_inbox` for pending work — what another actor is waiting on this agent for, which is