docs(claude.md): steer Claude toward soul_observe for facts (post-#231)

[prakashUXtech]

What this PR changes

One line in .claude/CLAUDE.md, the agent-facing memory guide for this repo.

The "During work" section was telling Claude to use soul_remember for "facts that should persist across sessions." Post-#231 that's wrong. soul_remember writes through MemoryManager.add() with no reconcile_fact, no contradiction check, no significance gate, so repeated calls with similar text just pile up. Issue #251 caught what that looks like in practice: one soul ended up roughly 51% duplicates before someone noticed and ran soul cleanup by hand.

The updated guidance points Claude at soul_observe for facts that come out of real user/agent turns, since observe runs the full pipeline including reconcile_fact. soul_remember is now scoped to blunt writes where the agent has already decided dedup is wrong (short episodic events, unique timestamped log lines). The bullet also flags that the CLI sibling soul remember is on a deprecation path toward soul note (#231 phase 2, currently PR #236) and that the MCP layer will pick up the dedup-aware variant once it ships.

Task 1 finding: the CLI deprecation warning is already in flight

The brief asked me to verify whether the post-#231 deprecation of soul remember had actually landed (no warning fires today) and to add a DeprecationWarning if the project clearly meant to ship one. Before touching code I read the history:

• Issue feat(cli): add 'soul observe' command with dedup pipeline; deprecate 'soul remember' #231 is the umbrella. Phase 2 explicitly says "Add a DeprecationWarning when soul remember is invoked, pointing at soul observe and the --no-dedup flag." Intent is unambiguous.
• PR feat(memory): add Soul.note() and 'soul note' CLI for dedup-aware writes (#231) #233 (merged) shipped Phase 1: Soul.note() runtime + soul note CLI. Phase 2 was deferred.
• PR chore(cli): deprecate soul remember in favor of soul note (phase 2 #231) #236 is OPEN and is the Phase 2 work, by a community contributor (Anshul, LFDT mentorship). It already adds warnings.warn(..., DeprecationWarning, stacklevel=2) to remember_cmd, prints a console.print deprecation banner, updates the help text, README, and CLI reference, and has a passing test. The review on chore(cli): deprecate soul remember in favor of soul note (phase 2 #231) #236 left four small change requests (CHANGELOG entry, removal-horizon version, docs header marker, test sharpening); the contributor says they've addressed them and is waiting on the CI PR (ci: run pytest matrix on PRs targeting dev (#241) #242) to land first.

Adding a second warning here would clobber that active community PR mid-review, so I skipped it. No new tracking issue needed either, since #231 (Phase 2) and #236 already cover the question.

One nuance at the runtime layer that's easy to misread: Soul.note()'s docstring describes remember() as "a blunt append," and note() itself falls through to remember() for episodic and dedup=False. The two coexist by design inside the runtime (note is the smart wrapper that calls remember underneath for the no-dedup paths). The deprecation lives at the CLI layer, which is where #236 is doing the work.

Why ship the docs update separately

The MCP recommendation is wrong today regardless of when #236 merges. The agent guide pointing at soul_remember for facts is what produced the #251 bloat in the first place. Once #236 merges and a soul_note MCP tool follow-up lands, this guide can be tightened again.

Verification

• Pure docs change, no Python touched, no test impact.
• git diff --stat confirms one file changed (.claude/CLAUDE.md, +2/-2).
• Read Soul.remember() (src/soul_protocol/runtime/soul.py:1391) and Soul.note() (src/soul_protocol/runtime/soul.py:1432) to confirm the runtime semantics described above. Read the soul_remember and soul_observe MCP definitions (src/soul_protocol/mcp/server.py:621, :574) to confirm no soul_note MCP tool exists yet.

Refs

• feat(cli): add 'soul observe' command with dedup pipeline; deprecate 'soul remember' #231 — umbrella issue (Phase 2 describes the deprecation intent)
• chore(cli): deprecate soul remember in favor of soul note (phase 2 #231) #236 — open PR shipping the actual CLI DeprecationWarning (do not duplicate)
• Duplicate memories accumulate unbounded — remember has no write-time dedup and consolidation is not automatic #251 — duplicate-memories incident that makes the recommendation update worth shipping now

Local testing

$ git diff --stat origin/dev...HEAD
 .claude/CLAUDE.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

$ git log --oneline origin/dev..HEAD
c2e5c49 docs(claude.md): steer Claude toward soul_observe for facts (post-#231)

[github-actions]

All quality checks passed. Thanks for the clean PR!