Why

Refs #1487. The integration must recover work across sessions and compaction, not merely expose a curated tool subset. This revision replaces the initial preview's queued checkpoint instructions with actual awaited writes and durable receipt reconciliation.

What Changed

• Every advertised MCP tool, original schema, paginated discovery, unchanged argument forwarding, and a persistent lifecycle-owned connection.
• Startup/reload/resume/branch recall reads the active branch's latest checkpoint and graph neighborhood, cwd-scoped checkpoints/tasks/decisions, topic matches, and shared recent activity. References enter context before the next prompt without an extra model turn.
• Ongoing knowledge capture at agent_settled, awaited checkpoints before manual/detailed/threshold/overflow compaction, restored checkpoint references afterward, and summaries of outstanding work on shutdown/replacement.
• Optional immutable public-message transcripts, distinct from synthesized knowledge. Handoffs link their prior checkpoint and captured transcript sources.
• Pending intents and confirmed receipts in Tau's active persisted branch. Reload reconciles by reading; sibling branches can recover shared source-tip captures. Ambiguous/missing/changed remote writes are not retried or overwritten automatically.
• /bm-orient, /bm-checkpoint, /bm-remember, /bm-status, explicit destination/capture controls, common credential masking, actionable failure notifications.
• Root package/agent checks and Tau CI wiring. Existing integrations are otherwise unchanged.

Implementation Details

bridge.py runs short-lived discovery in a joined thread during synchronous setup, then starts a persistent MCP owner task at session start. Active calls share it; shutdown cancels requests and closes contexts in the owner task. Every restart gets a fresh stop event (fixes the initial Codex finding).

continuity.py selects actual persisted public messages, not synthetic summaries, private reasoning, tool payloads, or custom recall context. It incrementally synthesizes against the prior handoff, with chunk limits and an overall deadline. Before remote writes it records an intent; confirmation requires a validated BM result and durable Tau receipt. Notes stay ordinary shared-graph Markdown.

results.py preserves native text/images, structured content, errors, and explicit serialization of other MCP blocks. privacy.py masks common credential forms, not arbitrary secrets.

Configuration is user-level or explicitly selected. It never guesses a shared/team destination, changes credentials, creates projects, installs dependencies, or patches installed Tau.

Upstream dependency

Implemented and opened separately: huggingface/tau#683, pinned here at f41242532a2e55c6ee7f96b71d6949d3db9c172d.

It supplies consistent awaited extension compaction callbacks, deep-copied active-branch entries, bounded tool-free active-model synthesis, zero-turn reference insertion, and lifecycle notifications for in-place tree branching. Stock Tau 0.4.1 lacks these APIs and fails with an actionable requirement. The isolated package environment uses the pinned fork; the installed user Tau remains untouched. HTTPX is constrained to the tested 0.x API/SOCKS extra rather than its development release.

Testing

• just fast-check: passed, including root Ruff/format and just typecheck.
• just package-check: passed across all consolidated packages; Tau target runs Ruff, format, ty and 49 hermetic tests (2 real-BM tests opt-in).
• just doctor: passed in its temporary project.
• In integrations/tau, BM_TAU_TEST_COMMAND=<worktree>/.venv/bin/bm uv run --with pytest-cov pytest --cov=tau --cov-report=term-missing -q: 51 passed, 100% statement coverage across all five integration runtime modules.
• git diff --check: passed.
• Upstream fork: 1881 passed, 2 Windows-only tests skipped, Ruff/format/mypy passed.

Tests use actual Tau CodingSession, storage, stdio MCP, all four compaction entry points, interrupted writes/receipts, cancellation, privacy controls, actual session reload and branch/resume. A headless Textual test submits /reload through the TUI. Real-BM tests write/read/search, capture transcripts, save checkpoints, compact, restore references, reload and resume using temporary HOME/configuration/notes, local routing, no auto-updates/semantic downloads/telemetry.

Risks / Rollout

• Requires the pinned upstream fork until CLI access to Basic Memory via auto-starting server (Ollama pattern) #683 is released. That PR does not close all of #506: separate threshold/manual frontend-iterator/TUI-status behavior is outside the extension callback change.
• Configuring a project enables synthesized writes by default. Active-model summaries add requests, latency, and ordinary provider billing; all automatic capture modes are configurable and documented.
• Observation callbacks are awaited but not veto hooks. A failed write can precede compaction that continues, and a process kill cannot run shutdown. Neither is reported as a confirmed checkpoint.
• Pending writes that cannot be reconciled remain visible and deliberately require investigation rather than a blind retry.
• Credential masking is not a general secret detector. Disable capture for sensitive public text; cloud/team destinations disclose captured knowledge to that destination.
• Model behavior is tested with deterministic providers. No paid live-model quality evaluation, production memory, or cloud-account end-to-end test was performed.

Reviewer Guide

Read integrations/tau/DESIGN.md and README for the lifecycle/privacy contract, then continuity.py for state/receipts and bridge.py for ownership. The implementation and upstream changes remain separate PRs. No merge is authorized.