Memory names, slash-canonical paths, and the onConflict model

[cevian]

Summary

Adds an optional, human-chosen name to memories and reworks how memories are addressed, how tree paths are represented on the wire, and how write conflicts are handled. The UUID remains the immutable identity — everything here changes the contract around it.

This PR is best read by its semantic changes rather than its commits.

Semantic changes

Names & addressing

• A memory may carry an optional name — a filename-like slug (^[A-Za-z0-9][A-Za-z0-9._-]*$, ≤128 chars, dots allowed / slashes not), unique within its tree.
• New path addressing: memory.getByPath / memory.deleteByPath take a folder/name path (split on the final /). memory.get / delete stay id-addressed. CLI me get / me delete auto-detect UUID-vs-path; me update resolves a path to an id first.
• create / batchCreate still accept an explicit id (import/export identity); update gains name (set/rename; null or "" clears).

Tree paths are now slash-canonical — breaking (wire/display)

• The API and CLI now emit paths in leading-slash form: root /, /share/auth, home ~/notes (previously dotted, share.auth). ltree storage stays dotted internally.
• Input is unchanged and lenient: /share/auth, share/auth, and dotted share.auth all normalize the same. Only output changed — anything that string-matches a returned tree must now expect the slash form.

Conflict handling: onConflict — breaking (default behavior)

• create / batchCreate take onConflict: 'error' | 'replace' | 'ignore', default error. Previously a duplicate explicit id was silently skipped; it now raises CONFLICT unless replace/ignore is requested.
• The idempotency key is the explicit id when given, else the (tree, name) slot — and a name takes precedence over the id (a named row dedups on (tree, name) even when it also carries an id; the id is then just the row's identity on insert).
• replace is content-aware: a no-op unless content/meta/temporal differ, and re-embeds only when content changes.
• The old replaceIfMetaDiffers parameter is removed — content-aware replace subsumes it.
• File importers (me import memories, me_memory_import, me pack install) submit with ignore (idempotent re-import); transcript/git importers with replace plus a deterministic meta.importer_version stamp, so a version bump re-renders.

Importers re-keyed to (tree, name) — breaking (data layout)

• Transcript/git importers no longer derive deterministic hash-UUIDs. They mint a timestamp-prefixed random UUIDv7 (so chronological-by-id ordering and the incremental watermark still work) and key idempotency on (tree, name):
  • transcripts: each session is its own tree node (…/agent_sessions/<session_id>), each message named msg_<message_id>;
  • git: each commit is a named leaf <sha> under …/git_history.
• The per-run imported_at meta stamp was dropped (it would have defeated the content-aware re-import no-op).

Export

• Markdown export now mirrors the tree — <dir>/<tree>/<name-or-id>.md (was a flat {id}.md) — with name in frontmatter. Round-trips re-import idempotently.

Web

• name is an editable frontmatter field; the browse-tree leaf label and search-result rows display it.

Breaking changes / migration notes

• Returned tree strings are slash-form now — update any consumer that compares them as strings.
• A duplicate-id create errors by default (was a silent skip) — pass onConflict: 'ignore' / 'replace' for the old behavior.
• replaceIfMetaDiffers is gone from batchCreate.
• The importer re-key is not backward-compatible with already-imported data: prior transcript/git memories used hash-ids under a flat agent_sessions node; after this, a re-import writes to the new nested (tree, name) layout with fresh ids, so old rows aren't recognized (and would be duplicated under the new paths) rather than updated in place. Pre-production, so likely fine — but worth a one-time reimport/wipe where it matters.

Verification

./bun run check:full is green against local Postgres: 620 unit · 869 integration · 24 e2e, 0 failures. One new incremental migration (005_memory_name.sql); SPACE_SCHEMA_VERSION → 0.0.4.

🤖 Generated with Claude Code

[jgpruitt]

Potential missed name plumbing in the interactive editor: memory.update and the SQL patch_memory path now support renaming/clearing name, and the editor/frontmatter code parses name, but the CLI editor update path does not include it in the update params.\n\nCurrent code only sends content/meta/tree/temporal:\nhttps://github.com/timescale/memory-engine/blob/763ec478d26d7be1e3adc1f095e3b923bf8d3802/packages/cli/commands/memory-edit.ts#L167-L174\n\nThat means editing the frontmatter name in me memory edit looks like it should work but the rename/clear is silently ignored. Should this add something like if (parsed.name !== undefined) updateParams.name = parsed.name;?\n\nI could not leave this as an inline review comment because packages/cli/commands/memory-edit.ts is not in the PR diff.

[cevian]

Good catch — fixed in 05d81f1.

It was a bit broader than the one-liner: memory-edit.ts predates names and has its own frontmatter handling, so name was missing in three spots, not just the update params:

• formatForEdit didn't emit the existing name, so a named memory didn't even show its name to edit;
• hasChanges didn't compare name, so a pure rename/clear could register as "no changes" and skip the update entirely;
• the update params dropped it.

All three now handle it, matching the web editor's frontmatter semantics: a value sets/renames, and removing the name: line from a previously-named memory clears it (null) — which the if (parsed.name !== undefined) form wouldn't have covered. Only sent when it actually changed. Added memory-edit.test.ts for the formatForEdit/hasChanges name round-trip (rename / clear / no-op).

[Copilot]

Pull request overview

Adds first-class memory names, introduces folder/name path addressing, switches returned tree paths to canonical slash form, and replaces the old conflict behavior with an explicit onConflict model across create/batchCreate—spanning the database schema/functions, engine store API, server RPC surface, client/CLI/Web, and docs.

Changes:

• Add optional memory.name (validated, unique per (tree, name) when non-null) and surface it through RPC/client/engine/web/CLI.
• Add path-addressed RPC methods (memory.getByPath, memory.deleteByPath) and update CLI/MCP/docs accordingly.
• Make returned/display tree values slash-canonical (/share/auth, ~/notes, /) and add onConflict: error|replace|ignore to create/batchCreate (default error).

Reviewed changes

Copilot reviewed 73 out of 74 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/web/src/lib/tree-build.ts	Prefer name for leaf titles
packages/web/src/lib/tree-build.test.ts	Add name title preference test
packages/web/src/lib/frontmatter.ts	Support name in editor frontmatter
packages/web/src/lib/frontmatter.test.ts	Add name frontmatter coverage
packages/web/src/components/viewer/FrontmatterBlock.tsx	Display name in viewer panel
packages/web/src/components/SearchResultRow.tsx	Show name in search rows/menu
packages/web/src/components/editor/EditorPane.tsx	Send name in update mutations
packages/web/src/api/queries.ts	Convert slash paths → dot internally
packages/server/rpc/memory/memory.ts	Add name/path methods + onConflict handling
packages/server/rpc/memory/memory.integration.test.ts	Extend integration tests for name/paths/slash trees
packages/server/rpc/memory/management.integration.test.ts	Update grant path expectations to slash form
packages/protocol/memory.ts	Add name/onConflict + get/deleteByPath schemas
packages/protocol/memory.test.ts	Add schema unit tests
packages/protocol/fields.ts	Add memoryNameSchema + onConflictSchema
packages/engine/space/types.ts	Add name + OnConflict types
packages/engine/space/db.ts	Plumb name/onConflict; add resolveMemoryId
packages/engine/space/db.integration.test.ts	Cover name + onConflict semantics
packages/database/space/version.ts	Bump SPACE_SCHEMA_VERSION
packages/database/space/path.ts	Slash-canonical denormalized tree paths
packages/database/space/path.test.ts	Update tests for slash form
packages/database/space/migrate/migrate.ts	Add incremental 005 migration
packages/database/space/migrate/migrate.integration.test.ts	Expect new migration/function/index
packages/database/space/migrate/incremental/005_memory_name.sql	Add memory.name + unique index + check
packages/database/space/migrate/idempotent/002_search.sql	Add name return column; guarded drops
packages/database/space/migrate/idempotent/001_memory.sql	Add name columns + resolve/raise_conflict + conflict model
packages/client/memory.ts	Add getByPath/deleteByPath client methods
packages/cli/parsers/validation.ts	Validate/emit name in imports
packages/cli/parsers/index.ts	Extend ParsedMemory with name
packages/cli/parsers/import.test.ts	Add name parsing tests
packages/cli/mcp/server.ts	Add MCP tools + on_conflict/name support
packages/cli/importers/uuid.ts	Switch to timestamp-prefixed uuidv7 minting
packages/cli/importers/uuid.test.ts	Update tests for uuidv7At behavior
packages/cli/importers/index.ts	Re-key transcript import to (tree,name) + replace
packages/cli/importers/index.test.ts	Generalize dedup helper tests
packages/cli/importers/git.ts	Name commits by sha; use uuidv7At
packages/cli/importers/git.test.ts	Update expectations for name/id behavior
packages/cli/commands/pack.ts	Pack install uses onConflict ignore
packages/cli/commands/memory.ts	Add --name, path get/delete, onConflict flags
packages/cli/commands/memory-import.ts	Import uses onConflict ignore + carries name
packages/cli/commands/import-git.ts	Git import dedups by sha + replace
packages/cli/chunk.ts	Replace replaceIfMetaDiffers with onConflict option
packages/cli/chunk.test.ts	Update chunking tests for onConflict
e2e/cli.e2e.test.ts	Update e2e for slash trees + named-path flows
docs/typescript-client.md	Document slash trees, name, onConflict, getByPath
docs/memory-packs.md	Update examples to slash paths
docs/mcp/me_memory_update.md	Document name field + slash tree
docs/mcp/me_memory_tree.md	Update tree examples to slash form
docs/mcp/me_memory_search.md	Update tree filter examples to slash form
docs/mcp/me_memory_mv.md	Update move examples to slash form
docs/mcp/me_memory_import.md	Document name + onConflict ignore behavior
docs/mcp/me_memory_get.md	Add name field + point to get_by_path
docs/mcp/me_memory_get_by_path.md	New doc for get-by-path tool
docs/mcp/me_memory_export.md	Document tree-mirroring markdown export
docs/mcp/me_memory_delete.md	Point to delete_by_path/delete_tree
docs/mcp/me_memory_delete_tree.md	Update examples to slash form
docs/mcp/me_memory_delete_by_path.md	New doc for delete-by-path tool
docs/mcp/me_memory_create.md	Document name + on_conflict + slash trees
docs/mcp-integration.md	Add new MCP tools + slash examples
docs/getting-started.md	Update quickstart for slash trees + name
docs/formats.md	Add name field + slash-canonical tree docs
docs/concepts.md	Add name/addressing/conflict model + slash trees
docs/cli/me-pack.md	Update semantics to onConflict ignore
docs/cli/me-memory.md	Update CLI docs for name/path + slash trees
docs/cli/me-mcp.md	Update defaults to slash paths
docs/cli/me-import.md	Update git layout/idempotency docs
docs/cli/me-claude.md	Update CLAUDE.md pointer tree examples
docs/cli/me-agent.md	Update home path examples to slash form
docs/cli/me-access.md	Update grant examples to slash form
docs/cli/agent-session-imports.md	Update transcript importer layout/idempotency
docs/access-control.md	Update access-control examples to slash form
CLAUDE.md	Update project model summary for name/paths/onConflict

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cevian]

Fixed in 278f070. create_memory now returns the stored id (the kept existing id on a (tree, name) update/skip), and the handler uses it directly instead of created?.id ?? params.id ?? resolve(...). So a named re-submit with a fresh explicit id resolves to the existing row — no INTERNAL_ERROR.

[cevian]

Fixed in 06e67e7 — getByPath now uses a new memoryPathSchema that validates the leaf (segment after the final /) with memoryNameSchema and rejects a trailing /. So a typo'd path fails with VALIDATION_ERROR instead of masquerading as NOT_FOUND. The tree portion stays lenient.

[cevian]

Fixed in 06e67e7 — same memoryPathSchema applied to deleteByPath.

[cevian]

Fixed in 06e67e7 — me memory create --name "" now errors immediately ("omit --name for an unnamed memory") instead of silently creating an unnamed memory. Clearing a name remains an update-only op (update --name "").

[jgpruitt]

Protocol docs appear to contradict the implemented name-precedence behavior for create/batchCreate conflicts.

The comments here say the idempotency key is the explicit id when present, else (tree, name):

• memory-engine/packages/protocol/memory.ts

  Lines 24 to 27 in 1a2d124

  	* `id` is optional — supply it to preserve identity (import/export, deterministic
  	* importers); omit it for a server-generated uuidv7. `name` is the optional leaf
  	* slug. `onConflict` governs a clash on the idempotency key (the id when given,
  	* else the (tree, name) slot): default `error`.

• memory-engine/packages/protocol/memory.ts

  Lines 44 to 46 in 1a2d124

  	* `onConflict` governs a clash on each row's idempotency key (its id when given,
  	* else its (tree, name) slot): `error` (default) raises, `replace` overwrites
  	* in place when content/meta/temporal differ (a no-op when identical), `ignore`

• memory-engine/packages/protocol/fields.ts

  Lines 80 to 83 in 1a2d124

  	* What a create/batchCreate row does when it conflicts with the existing memory
  	* on its idempotency key (the explicit id when given, else the (tree, name)
  	* slot): `error` (default) raises CONFLICT; `replace` overwrites in place but is
  	* a no-op when nothing changed; `ignore` skips, leaving the existing row.

But the SQL implementation makes name take precedence whenever name is present: named rows are deduped on (tree, name) even when an explicit id is supplied, and the supplied id is only used as the row identity on a fresh insert. On a (tree, name) conflict, the existing row/id is kept.

These protocol comments should probably say that named rows use (tree, name) as the idempotency key, and unnamed explicit-id rows use id.

[jgpruitt]

we don't need this drop function do we?

[cevian]

You're right — removed in 40fa547. The (ltree, text) signature never existed on main or anywhere in the branch (only the 0-arg raise_conflict() was ever created), so the drop was a no-op running every migration.

[jgpruitt]

Say I'm using (tree,name) for idempotency and I pass in 125 memories. 1 gets skipped. I get 124 rows of results, but I have no way of knowing which one was skipped. Also, because I only get 124 rows back, I cannot match up the returned ids with the source rows--I don't know which id goes with which (tree,path).

Ideally, I'd get 125 rows back in the same order i inserted them with an indication of which one was skipped. Something like this:

returns table
( ord bigint
, id uuid
, status text -- inserted | updated | skipped
)

[jgpruitt]

another option is to treat duplicate explicit ids and duplicate (tree,name)s in input as an error

[cevian]

Done — and thank you for the exact shape. 278f070 makes batch_create_memory return (ord, id, status) (one row per input, in input order; status inserted | updated | skipped). f3360a9 surfaces it on the wire as { results: [{ id, status }] }, so callers can map each result back to its input and see skips.

[jgpruitt]

names are parsed but not inserted. they are dropped. see line 233

[cevian]

Fixed in 8f8ce9f — pack install now passes each memory's name through to batchCreate (it was parsed but dropped at the createParams step).

[jgpruitt]

Names are unique in the database, but filesystem names can still collide. For example, foo and foo.md are distinct memory names in one tree but both export to foo.md.
Case-insensitive filesystems introduce more possible collisions.

[cevian]

Fixed in 4705be0 — added uniqueExportFilename, which tracks claimed filenames per directory (compared lowercased, so Foo/foo are treated as colliding for portability) and inserts the memory's unique id before .md on a clash, e.g. foo + foo.md → foo.md and foo.<id>.md. If even the id-disambiguated name is taken it throws rather than guessing.

[jgpruitt]

Export uses <tree>/<name-or-id>.md, appending .md unless the name already ends with .md.
Names are unique in the database, but filesystem names can still collide. For example, foo and foo.md are distinct memory names in one tree but both export to foo.md.
Case-insensitive filesystems introduce more possible collisions.

[cevian]

Fixed in 4705be0 — the MCP directory export uses the same uniqueExportFilename helper.

[jgpruitt]

Generated Importer Names Can Be Invalid or Collapse Distinct IDs

• messageName() replaces invalid chars with _, but does not cap at the 128-character name limit.
• Distinct message ids like a/b, a:b, and a_b collapse to the same name.
• sessionTree() uses normalizeSlug(sessionId), which can similarly conflate session ids into one tree.

[cevian]

Fixed in 8f8ce9f. messageName and sessionTree now route through a new boundedUniqueLabel: it caps at the 128-char name limit and appends a hash of the full original id whenever the slug is lossy or over-length — so a/b, a:b, a_b (and a UUID session id whose dashes merge in an ltree label) no longer collapse to one slot. Clean, fitting ids are unchanged. Covered by new unit tests.

[jgpruitt]

Don't we also need to consider named memories that didn't have explicit ids when computing how many were skipped?

[cevian]

Good catch — fixed in f3360a9. Skip counting now reads the server's per-row status instead of diffing explicit ids, so a named, id-less row skipped on its (tree, name) slot is counted. The old computeSkippedIds helper is gone.

[Copilot]

Pull request overview

Copilot reviewed 79 out of 79 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (3)

docs/mcp/me_memory_create.md:40

• In the space RPC model, createdBy is always null (the space schema doesn’t track per-memory creators; the server sets it to null in responses). The example response should reflect that to avoid misleading API/MCP consumers.

  "hasEmbedding": false,
  "createdAt": "2025-04-15T12:00:00Z",
  "createdBy": "user_abc",
  "updatedAt": null
}

docs/mcp/me_memory_get.md:28

• The space RPC layer always returns createdBy: null (there’s no per-memory creator in the space schema). This example currently shows a user id, which doesn’t match actual responses.

  "temporal": null,
  "hasEmbedding": true,
  "createdAt": "2025-04-15T12:00:00Z",
  "createdBy": "user_abc",
  "updatedAt": null

docs/mcp/me_memory_update.md:40

• The space RPC layer always returns createdBy: null (no per-memory creator tracking). This example response should use null to match real output.

  "hasEmbedding": true,
  "createdAt": "2025-04-15T12:00:00Z",
  "createdBy": "user_abc",
  "updatedAt": "2025-04-15T14:00:00Z"

[cevian]

Fixed in 8151819 — the comment now reads "an absent or empty name → null", matching coerceName (which normalizes both to null).

[cevian]

Fixed in 8151819 — CLAUDE.md now describes the per-row { results: [{ id, status }] } shape, and the idempotency-key note reads name-wins (this file was the one the R8 doc sweep missed).

[cevian]

This one's actually working as intended for the MCP tool. The tool's name input is z.string().optional().nullable() (no min(1)), and the handler maps "" → null before calling the RPC (server.ts:429) — so passing "" does clear the name via me_memory_update, mirroring the CLI's update --name "". The min-1 memoryNameSchema you spotted is on the RPC param, which the tool never sees "" for. So the doc is accurate; leaving it.

[cevian]

Correct — per-memory meta.pack is rejected by validatePackConstraints and the installer injects the pack.<name> prefix. This is actually broader: the whole example here is the old v1 flat-array format (header comments + bare array), which the current parser rejects in favor of the v2 envelope (name/version/id-prefix/format/memories). That staleness predates this PR (it's already on main; this branch only slash-converted these lines), so I'm leaving it out of the memory-names PR and will fix the pack-authoring docs to v2 in a separate change.

[cevian]

Same as the sibling example — meta.pack rejection and the relative-tree / pack.<name> prefix are part of the same pre-existing v1→v2 pack-doc staleness (on main already). Tracking it as a separate pack-docs fix rather than expanding the scope of this PR.

[jgpruitt]

Here we skip if there is a collision on ids but we don't have write access the existing memory's tree. This behavior seems to contradict _on_conflict = 'error'

[jgpruitt]

Explicit-id collision against an existing row outside the caller’s writable tree silently becomes skipped. In memory.create, packages/server/rpc/memory/memory.ts:233-246 then tries to read that inaccessible id and returns INTERNAL_ERROR instead of CONFLICT.

[jgpruitt]

This attributes batch results by joining acted back to inputs on id only. If two inputs resolve to the same stored id through different keys, e.g. existing named row X, one input {id: X} and another {tree, name} with no explicit id, one row’s update marks both inputs as updated. The duplicate checks at 267-286 don’t catch this because the idempotency keys differ. This breaks the “one status per input” contract.

[jgpruitt]

I think we need a check that goes something like this:

  select exists
  (
    select x.id, count(*)
    from
    (
      select m.id
      from unnest(_ids) u(id)
      inner join {{schema}}.memory m on (u.id = m.id)
      union all
      select m.id
      from unnest(_trees, _names) u(tree, name)
      inner join {{schema}}.memory m on (m.tree = u.tree and m.name = u.name)
      where u.name is not null
      and m.name is not null
    ) x
    group by x.id
    having count(*) > 1
  )

[jgpruitt]

i.e. find any occurences where both an explicit id input and a tree name input would update the same existing memory