feat(integrations): unify Tau memory schemas and setup

[phernandez]

Why

Follow-up to #1489; refs #1487. Basic Memory's value is shared, structured knowledge that any connected agent can find and understand. Tau's first integration delivered lifecycle continuity but emitted coding_session notes without the established Git identity fields and used cwd-only recall. Its setup also lacked the schema/placement conventions already present in the hook-backed integrations.

This aligns the memory contract without invoking bm hook, importing CLI orchestration, or adding a generic host framework. Sidebar/custom-frontend work is deliberately separate.

What Changed

• Canonical Coding Session, Session, Task, and Decision schemas in integrations/shared/schemas, with checked copies in Claude Code, Codex, and Tau packages. Codex keeps its existing separate general-session schema. Adds optional tau_session_id and host-neutral prose without changing existing required fields.
• Explicit user-owned coding profiles keyed by absolute checkout root, with confirmed repository identity, their own write project, read-only recall sources, and placement conventions. General configuration remains supported; lifecycle flags remain global.
• Coding checkpoints carry actual Git root/branch/SHA, optional PR fields, project/timestamps/capture method, and Tau session identity. General checkpoints use session, not a misleading coding_session type. Synthesis instructions use the shared schema categories.
• Repository-scoped coding recall across worktrees; active tasks/open decisions; approved read-only shared sources; bounded knowledge discovery. No unscoped recent-session feed in coding profiles. Unconfigured nested Git checkouts cannot inherit the parent's coding recall or capture route.
• A discoverable setup skill with destination/profile consent, cost/privacy disclosure, schema seeding with approval, preservation of custom schemas/configuration, separate connectivity/schema/write verification, and reload/shutdown caveats.
• Pins the Basic Machines Tau fork at d8216af0b34059839734422d1e39b4c5972d7966, including the single-copy snapshot fix. Upstream contribution: feat: support awaited extension continuity across compaction huggingface/tau#687 (replaces CLI access to Basic Memory via auto-starting server (Ollama pattern) #683).

Implementation Details

knowledge.py contains validated configuration profiles, a small frozen Git-context value, bounded asynchronous metadata reads, and placement guidance. The lifecycle remains in continuity.py; MCP discovery, ownership, argument forwarding, and receipts retain their existing boundaries. Missing/failed/timed-out optional GitHub lookup omits PR context; invalid successful payloads and required Git failures surface rather than fabricating identity.

A coding profile never inherits the global write destination implicitly. Its root must match Git's top-level directory; additional worktrees require explicit user configuration with the same stable repository identity. Secondary projects are used only in automatic read operations. Explicit agent tool arguments remain unchanged.

Existing config keys and durable receipts remain compatible. Existing notes are not rewritten to retrofit metadata; general cwd recall can still find legacy snapshots. Canonical schemas are bundled as copies for self-contained installation; scripts/sync_memory_schemas.py --check and package tests detect drift. This does not rewrite installed user schemas or create a lifecycle-event-to-knowledge pipeline.

Testing

On the rebased branch, based on 9cd8169ea:

• just fast-check: passed, including root Ruff/format/typecheck.
• just package-check: passed across all packages. Tau: 66 passed, 3 opt-in real-BM tests skipped, Ruff/format/ty passed.
• just doctor: passed in a temporary project.
• From integrations/tau: BM_TAU_TEST_COMMAND=<worktree>/.venv/bin/bm uv run --with pytest-cov pytest --cov=tau --cov-report=term-missing -q: 69 passed; 100% statement coverage across six runtime modules (617 statements).
• git diff --check: passed.

New evidence covers actual Git metadata, missing/invalid optional PR results, cancellation cleanup, explicit profile selection, nested/unborn checkout safety, read-only source routing, real Tau skill loading/invocation, and schema bundle parity. Real-BM tests seed the shared schemas, validate a Tau checkpoint with no warnings/errors, find it using the hook-style repository query, and recall Tau plus a schema-valid other-host fixture from another actual Git worktree while excluding both from a different repository's coding brief.

Existing actual Tau compaction/reload/branch/resume, headless TUI reload, receipt failure/reconciliation, privacy, and persistent MCP tests still pass. Model synthesis uses deterministic fake providers. No paid live-model, production memory, or cloud-account test was performed.

Risks / Follow-ups

• Still requires upstream Tau FTS-based session/conversation search for episodic recall #687 or the pinned organization fork; no installed Tau packages were patched.
• Automatic synthesis adds model cost and latency; Git/optional PR reads add bounded metadata I/O.
• Read-only memory sources still disclose recalled content to the active model. Captures go only to the explicitly selected write destination. Credential masking remains best-effort.
• Reload closes the old lifecycle before loading new config, so a final shutdown capture may still use the previous destination/settings.
• A custom user schema is not overwritten automatically; setup surfaces incompatibility for an explicitly approved migration.
• Receipt identity is intentionally preserved. Already-confirmed captures are reused rather than rewritten merely because a profile or schema changed.
• A Tau sidebar for destination, recall sources, confirmed checkpoint and outstanding work is a separate follow-up. No UI features or additional lifecycle trace store are introduced here.

No merge is authorized.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-06T16:04:23.115355Z	ba08df1	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.