Basic Memory Setup for Tau

Set up Basic Memory in Tau

Help the user choose where memory goes and what gets saved. Ask one decision at a time. Set up Basic Memory's shared workflow: schema-backed checkpoints, tasks, decisions, categorized observations, and verified relations that other agents can find. Tau provides the lifecycle callbacks; it does not define a separate memory system. Do not create projects, reorganize notes, change credentials, or install packages as incidental setup work.

1. Inspect before changing anything

• Locate the integration directory: the installed ~/.tau/extensions/basic-memory from bm install tau, or integrations/tau in an explicitly identified Basic Memory checkout. Do not assume the current directory or this skill's directory contains the extension. A packaged install does not require a source checkout.
• Read the integration directory's README.md, pyproject.toml, bridge.py, and knowledge.py for installation instructions, the dependency pin, Settings, and the general/coding profile models. Published reference: https://github.com/basicmachines-co/basic-memory/blob/feat-tau-1487/integrations/tau/README.md
• Check executable availability with command -v uv, command -v bm, and command -v tau. Inspect versions/help only for executables that exist. The integration requires Python 3.13+, uv, and a configured Basic Memory CLI.
• Distinguish the user's installed Tau from the isolated integration environment. Stock Tau 0.4.1 lacks continuity APIs. The upstream contribution is https://github.com/huggingface/tau/pull/687, from Basic Machines. Use the checked-in immutable dependency pin, not an invented version or a moving branch. A version string alone cannot distinguish stock 0.4.1 from its compatible fork.
• Identify the effective config path: TAU_BASIC_MEMORY_CONFIG if explicitly set, otherwise ~/.tau/basic-memory.json. Inspect only that file, not unrelated Tau catalogs, credentials, logs, or conversation storage. Never dump its contents into output. Do not accept repository-local config as a capture destination.
• If the extension is loaded, ask the user to run /bm-status. A text reply does not run a slash command or control the current Tau session. Do not start a second Tau process against the current session's storage.

If prerequisites are absent, explain the missing prerequisite and obtain approval for the specific installation. Consult current Basic Memory install docs rather than guessing package versions or changing the user's global Tau installation.

2. Choose destination and policy

Offer tools only, recall only, or full continuity. Recommend full continuity for ordinary coding only after explaining its costs and disclosure.

For recall or continuity, list existing projects using the advertised bm_list_memory_projects tool when available, or bm project list. Check current CLI help or tool schemas for routing arguments. Identify local/cloud/team routing for the exact destination; if routing cannot be established, stop and ask. Do not dump Basic Memory's config or authentication material. Ask the user to choose an existing project explicitly, including its workspace when applicable. Never select the default project or a team workspace on the user's behalf.

Explain:

• Full continuity sends new public user/final-assistant text and the prior handoff to Tau's active model for synthesis. It adds requests, latency, and model billing.
• Notes are saved to the selected Basic Memory project. Cloud/team destinations disclose those notes there; get explicit approval for that destination.
• Recall-only still retrieves note contents into Tau's model context. Local notes do not imply local model inference. It disables automatic writes, not explicit tool calls or /bm-checkpoint and /bm-remember requests.
• Transcripts stay off unless separately requested. Hidden reasoning, raw tool payloads, and images are excluded from automatic capture. Credential masking is best-effort, not a general secret detector. Recommend tools-only for sensitive sessions; even explicit tool calls can disclose data.

Also ask about optional read_projects (up to six explicit read-only sources). Explain that shared context does not authorize writes back to those projects. Choose placement_conventions based on a small approved inspection of existing notes. Checkpoints belong in their configured folder; durable decisions and tasks belong with their topics, linked from checkpoints rather than duplicated each turn.

Use these policy overlays, replacing CHOSEN_PROJECT only after approval:

Tools only

{
  "project": null,
  "auto_recall": false,
  "capture_knowledge": false,
  "checkpoint_on_compact": false,
  "summarize_on_shutdown": false,
  "capture_transcript": false
}

Recall only

{
  "project": "CHOSEN_PROJECT",
  "auto_recall": true,
  "capture_knowledge": false,
  "checkpoint_on_compact": false,
  "summarize_on_shutdown": false,
  "capture_transcript": false
}

Full continuity

{
  "project": "CHOSEN_PROJECT",
  "auto_recall": true,
  "capture_knowledge": true,
  "checkpoint_on_compact": true,
  "summarize_on_shutdown": true,
  "capture_transcript": false
}

Coding sessions default to tau/{repo name} within the chosen project, using the final component of the confirmed repository identity, not the worktree directory name. General sessions default to tau/checkpoints; separately enabled transcripts use tau/transcripts. Omit checkpoint_folder (or use null) for automatic placement; set it explicitly only for a user-approved override. Preserve existing folder, command, arguments, timeout, and budget settings unless the user approves changing them. Never put API keys in this file; Basic Memory owns authentication and project routing.

General or coding profile

Ask whether this checkout is for coding or general work. Do not infer coding consent merely because Git is present. General checkpoints use session; coding checkpoints use the shared coding_session contract.

For coding, resolve the Git top-level root and stable repository identity, such as owner/name. Inspect remotes narrowly without echoing embedded credentials. Ask the user to confirm both; do not invent an identity when remotes are ambiguous. Explain that branch, SHA, cwd, and optional PR metadata are saved with checkpoints. The repository label is user-confirmed identity, not a write destination.

Store coding profiles only in the user-owned repositories list. Each entry has an absolute checkout root, repository, kind: coding, and its own explicit project/read sources/placement. It does not inherit the global project. The closest matching root wins; Git must confirm that exact root before a coding write. Register another worktree explicitly with the same repository identity. Never silently copy a parent's mapping into a nested Git checkout.

Example configuration for coding in one approved checkout and tools-only elsewhere (the global lifecycle flags still apply to every profile):

{
  "project": null,
  "repositories": [
    {
      "kind": "coding",
      "root": "/absolute/path/to/approved-checkout",
      "repository": "owner/repository",
      "project": "CHOSEN_PROJECT",
      "read_projects": [],
      "placement_conventions": "Decisions in decisions/, tasks in tasks/. Search before creating notes."
    }
  ],
  "auto_recall": true,
  "capture_knowledge": true,
  "checkpoint_on_compact": true,
  "summarize_on_shutdown": true,
  "capture_transcript": false
}

Do not replace other repository entries when updating this checkout. A general user-level project applies outside configured coding roots; confirm that broader scope explicitly. Opt-out flags disable automatic operations across profiles. Existing legacy Tau receipts remain usable; old notes are not silently rewritten to retrofit repository metadata.

3. Apply approved configuration

Show a safe summary of the proposed destination, policy, effective config path, and changes. Ask for approval before writing. These examples are overlays, not permission to overwrite an existing config wholesale.

Parse the existing JSON strictly. If malformed or containing unknown fields, stop and explain the problem without printing sensitive values; do not replace it with defaults. Merge the approved fields and validate the complete candidate using tau.bridge.Settings.model_validate in the integration's environment, before writing. Do not print the config, validation input values, or unfiltered exceptions. Report invalid field paths and a safe explanation. Validation must not start MCP or call a model. Preserve the existing file's permissions and use a private file for a new config; avoid leaving backups containing private arguments in the checkout.

Write only after successful validation. Report configuration validation separately from connection or end-to-end verification. If already configured correctly, leave it unchanged and proceed to verification.