[qingyun-wu]

Summary

• Renames the Memory-space env var from SUTANDO_PRIVATE_DIR to SUTANDO_MEMORY_DIR so vocabulary matches the 3-space mental model (Code / State / Memory) ratified in docs: add workspace-design.md — 3-space model RFC (Code/State/Memory) #858 Decision 2.
• One-release alias: SUTANDO_PRIVATE_DIR continues to work as a fallback, with a deprecation warning emitted to stderr on every read (cron / launchd miss startup-only warnings — every-read is intentional).
• 10 Python + 5 TS unit tests cover precedence, legacy fallback, deprecation-on-every-read, and the both-set-prefer-new case.

What changed

New helper (single source of truth for the lookup):

• Python — _memory_dir_env() in src/util_paths.py
• TypeScript — memoryDirEnv() exported from src/util_paths.ts

Both return SUTANDO_MEMORY_DIR when set, else SUTANDO_PRIVATE_DIR with a DEPRECATION warning, else None/undefined.

Call-site updates:

• src/util_paths.{py,ts} — personal_path() / personalPath() + shared_personal_path() / sharedPersonalPath() route through the helper.
• src/inline-tools.ts — loadSkillManifestTools(), loadCoreDocumentedSkills(), and the open_file tool description.
• src/voice-agent.ts — voice-context dynamic loader.
• skills/phone-conversation/scripts/conversation-server.ts — inline personalPath() twin (kept inline to avoid pulling main repo's util_paths.ts through the skill's import surface).
• src/session-handoff.sh — passes both env vars through to the python child.
• Docs: CLAUDE.md, docs/workspace-contract.md, skills/MANIFEST.md.

Risk to existing users

None. Anyone with only SUTANDO_PRIVATE_DIR set:

1. Keeps working — value still resolves correctly through the legacy path.
2. Sees a one-line DEPRECATION warning on stderr per read.
3. Can migrate at their own pace by renaming the env var in their shell rc / launchd plist / .env.

The legacy alias will be removed in the next release.

Test plan

• python3 tests/util-paths-memory-dir.test.py — 10/10 pass
• npx tsx --test tests/util-paths-memory-dir.test.ts — 5/5 pass
• python3 tests/workspace-default.test.py — still 27/27 pass
• npx tsc --noEmit clean
• CI on the PR

Closes #870

🤖 Generated with Claude Code

[liususan091219]

Solid rename + deprecation alias pattern. Three notes:

1. Every-read deprecation warning may flood stderr in hot paths. The comment explicitly defends this ("cron environments miss startup-only warnings, so logging at every resolution is intentional"). Fair for cron — cron runs the script once per fire, so every-read is once-per-fire. But for long-running daemons (voice-agent, discord-bridge, telegram-bridge, slack-bridge) that call personalPath() / sharedPersonalPath() repeatedly, this becomes log spam. Suggest a module-level "warned-once-per-process" sentinel: still fires once per cron invocation (which is what cron needs), but doesn't flood the daemon logs. Two extra lines.

2. loadSkillManifestTools() resolves memoryDirEnv() at module-init time (in inline-tools.ts:1037ish) — fine as long as no test mutates process.env.SUTANDO_MEMORY_DIR between agent restarts, which I don't think any does. Just calling out the import-time read so it's a deliberate choice, not an accidental capture.

3. conversation-server.ts keeps its inline personalPath() twin with manually-duplicated deprecation-warn code. PR body acknowledges this is intentional (skill import-surface isolation). When/if hostLabel() logic shifts in #877 follow-ups, both sites need updates — worth a // keep in sync with src/util_paths.ts:hostLabel() comment over the inline twin to make the duplication discoverable.

Docs are thorough (CLAUDE.md / workspace-contract.md / MANIFEST.md all updated, 4 spots touched). 10 Py + 5 TS tests is right-sized for a rename + alias. LGTM net.

[vidhuUC]

APPROVE. Clean env rename with proper one-release backward compat. All the callsites I spot-checked (CLAUDE.md, workspace-contract.md, MANIFEST.md, conversation-server.ts) consistently use the new name with legacy fallthrough commentary. The pattern SUTANDO_MEMORY_DIR || SUTANDO_PRIVATE_DIR is applied uniformly. CI green.