Document memory systems and deprecate unstructured SimpleMemoryStore

[Copilot]

UACS has two memory systems: the modern Semantic API (v0.3.0) with structured Pydantic models and rich metadata, and the legacy SimpleMemoryStore that accepts unstructured dict[str, Any]. The "basic strings" concern applies only to SimpleMemoryStore—examples already use Semantic API correctly.

Changes

Deprecation

• Added DeprecationWarning to SimpleMemoryStore.__init__() directing users to Semantic API
• Marked for removal in v1.0.0

Documentation

• MEMORY_SYSTEM_REVIEW.md - Comprehensive analysis comparing both systems, identifies the structured vs unstructured issue, provides 7 prioritized recommendations
• docs/MIGRATION_SIMPLE_TO_SEMANTIC.md - Migration guide with before/after examples, automated migration script, and troubleshooting
• README.md - Updated memory section to prominently feature Semantic API as recommended approach
• REVIEW_SUMMARY.md - Executive summary of findings

Verification

• verify_memory_review.py - Script validating deprecation warning, documentation completeness

Comparison

SimpleMemoryStore (deprecated):

store.store("key", {"note": "value"})  # Accepts any dict[str, Any]

Semantic API (recommended):

uacs.add_decision(
    question="How should we handle API authentication?",
    decision="JWT with RS256 asymmetric signing",
    rationale="Stateless, scalable, works well with microservices",
    alternatives=["Session-based", "OAuth2", "API keys"],
    decided_by="team",
    session_id="auth_session_001",
    topics=["security", "authentication"]
)

The Semantic API already provides: Pydantic validation, semantic search, 7 typed categories (UserMessage, AssistantMessage, ToolUse, Convention, Decision, Learning, Artifact), confidence scores, provenance tracking, and automatic deduplication.

Impact

Non-breaking. Existing SimpleMemoryStore usage continues to work with deprecation warnings. Migration path documented for v1.0.0 removal.

Original prompt

Review the context and memory system. We should have a structured way of adding memories. In our example I'm just seeing basic strings. Double check to confirm we are setting context/memories wit full details and appropriate metadata. Document your findings and suggestions.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.