Summary

PR-2 of the chunk_links series (private RFC mem-agent-share-chunk-links-rfc.md). PR-1 (#469) added the chunk_links table plus a one-shot back-fill from the legacy shared-from=<uuid> audit tags. This PR wires the writer into mem_agent_share and exposes the reader Python API so structured provenance (indexed fanout, FK-bounded cascade, O(depth) walk-back) is populated going forward, not just for pre-RFC rows.

• Public MCP surface is unchanged — mem_agent_share's signature, return shape, and copy-on-share semantics are identical. The link is a storage invariant.
• No schema change in this PR (that shipped in feat(storage): add chunk_links table + one-shot back-fill from shared-from tags #469).
• A mem_share_lineage MCP tool that exposes walk_share_chain is the optional PR-3 per the RFC and is intentionally out of scope here.

Why

Before PR-1, provenance was only recoverable via LIKE '%shared-from=%' scans over chunks.tags. That doesn't benefit from an index, breaks on UUID churn (reindex re-issues chunk ids), and can't be enforced across delete. PR-1 gave us the indexed, FK-bounded table. This PR makes mem_agent_share actually write into it so the structure is populated without waiting for a re-share.

Changes

Model (models.py)

New ChunkLink dataclass:

• target_id: UUID — non-null, PK component
• source_id: UUID | None — null after source delete (ON DELETE SET NULL) or back-fill of an unresolvable tag
• link_type: str — currently 'shared'; _VALID_LINK_TYPES in sqlite_schema.py is the single source of truth
• namespace_target: str — denormalized so "list everything shared out" is one index lookup
• created_at: datetime

Storage (storage/mixins/share_links.py, new)

ShareLinkMixin wired into SqliteBackend with four methods:

• add_chunk_link(source_id, target_id, link_type, namespace_target) — INSERT OR REPLACE, idempotent on (target_id, link_type). Validates link_type against _VALID_LINK_TYPES in Python (the table has no CHECK constraint so adding a type is one PR, not two).
• get_chunk_link(target_id, link_type='shared') — exact PK lookup.
• get_chunks_shared_from(source_id, link_type=None) — fanout via idx_chunk_links_source; optional link_type filter.
• walk_share_chain(target_id, *, link_type='shared', max_depth=100) — walks target_id → source_id backward. Cycle defence via visited set, plus max_depth as a worst-case ceiling. Stops (and includes the terminal row) when source_id IS NULL; returns [] for unknown targets.

Abstract StorageBackend protocol in base.py gets the four signatures too.

Writer (server/tools/multi_agent.py)

mem_agent_share now calls _mem_add_core (returns IndexingStats) instead of the MCP-wrapped mem_add (string only), so it can read stats.new_chunk_ids[0] — the freshly-indexed destination chunk — and pass it to add_chunk_link.

Writer failure is best-effort + logged, not fatal:

• The markdown file still gets the shared-from= tag (copy-on-share durability is untouched).
• A link-table error must not surface to the caller or roll back the copy.
• The back-fill migration already handles rows without link records on upgrade, so even a silent writer drop would self-heal on the next version bump.

Tests (+17 tests; total 2421 → 2438)

• test_chunk_links_writer.py — TestAddChunkLinkUnit pins the writer contract (round-trip, INSERT OR REPLACE on re-share, NULL source acceptance, invalid link_type rejection). TestMemAgentShareWritesLink verifies the end-to-end integration writes a row with the right (source_id, target_id, namespace_target) shape. TestMemAgentShareLinkSurvivesSourceDelete exercises the ON DELETE SET NULL flow through the MCP surface.
• test_chunk_links_reader.py — get_chunk_link (missing target, link_type filter); get_chunks_shared_from (empty fanout, multi-target ordering, link_type narrowing); walk_share_chain (happy path, NULL-terminal, unknown target, A↔B cycle, max_depth=3 on a 10-deep chain, max_depth=0 degenerate).
• test_multi_agent_integration.py — test_share_copies_chunk_with_audit_tag extended to assert both the pre-existing audit-tag behavior and the new chunk_links row.

One test I did not add: a multi-target "share this into two different namespaces" case. Turned out to expose a pre-existing indexer behavior (both shares append to the same daily markdown file and the second index_file(path, namespace=...) re-namespaces the first) — orthogonal to PR-2 and not something I want to slip into this series. Noting it here so it's tracked.

Test plan

• uv run ruff check packages/memtomem/src packages/memtomem/tests
• uv run ruff format --check packages/memtomem/src packages/memtomem/tests
• uv run pytest -m "not ollama" — 2438 passed, 46 deselected
• Targeted pass: pytest tests/test_chunk_links_{schema,writer,reader}.py tests/test_multi_agent_integration.py tests/test_multi_agent.py tests/test_storage_noop.py — 64 passed

🤖 Generated with Claude Code