Summary

mem_agent_share had three contradictory descriptions of what it does:

• Docstring line 127: "Creates a copy of the chunk in the target namespace"
• Comment line 146-147: "Create a cross-reference link instead of copying"
• Actual implementation: mem_add(...) — a brand-new chunk with a fresh
  UUID and no link back to the source.

The third version is the truth. The other two misled callers (and were
amplified on the multi-agent guide)
into expecting reference-link semantics that the storage layer does not
implement.

This PR:

1. Admits the function is a copy. Docstring rewritten to spell out
   that the new chunk has a fresh UUID, that delete/update on the source
   does not propagate, and that the name is preserved for API stability
   while true share semantics are tracked in a follow-up RFC.
2. Adds a shared-from=<source-uuid> audit tag to the copy so
   audit tooling can walk one hop back to the source. Tag uses =
   (not :) to avoid collisions with namespace-style tag schemes.
3. Dedups the audit chain on re-share. If the source already
   carried an inherited shared-from=... tag (from a prior share), it
   is dropped before appending the new stamp — so the new chunk holds
   shared-from=<immediate parent> only, never a growing chain.

The dedup logic is extracted into a top-level _build_shared_tags
helper so the contract is unit-testable without standing up MCP
components.

Out of scope (follow-up RFC)

True cross-reference linking — no duplication, bidirectional
propagation, storage-level chunk_links table — is a separate change
that needs schema migration. Tracked as a follow-up.

Test plan

• uv run pytest packages/memtomem/tests/test_multi_agent.py -v —
  15 pass (10 existing sanitize + 5 new TestSharedFromTags: fresh
  share, source-order preservation, single-parent dedup, multi-stale
  dedup, empty source tags).
• uv run pytest -m "not ollama" — 2334 passed, 46 deselected.
• uv run ruff check + ruff format --check — clean.

🤖 Generated with Claude Code