feat: Add salience-aware memory with reinforcement tracking (#186)

[Nsuccess]

Summary

Implements a memory lifecycle layer with deduplication, reinforcement tracking, salience-aware retrieval, and an optional LLM client wrapper for memU.

Closes #186

Features Implemented

1. Content Hash Deduplication

• compute_content_hash() generates unique hash for memory items
• Prevents duplicate memories by merging via reinforcement
• Normalizes whitespace and case for robust matching

2. Reinforcement Tracking

• reinforcement_count - tracks how often a memory is reinforced
• last_reinforced_at - timestamp of last reinforcement
• Existing memories get reinforced instead of duplicated

3. Salience-Aware Retrieval

• Formula: similarity × log(reinforcement+1) × recency_decay
• Configurable via ranking="salience" and recency_decay_days
• Frequently/recently mentioned facts surface first

4. Agent/Session Scoping

• Added agent_id and session_id to DefaultUserModel
• Enables multi-agent/multi-session memory filtering

5. LLM Client Wrapper (Stretch Goal)

• wrap_openai() convenience function
• Auto-injects recalled memories into prompts
• Fail-silent design - retrieval errors don't break LLM calls

Files Changed (9 files, +909 lines)

File	Change
src/memu/database/models.py	Added compute_content_hash, reinforcement fields
src/memu/database/inmemory/vector.py	Added salience_score, cosine_topk_salience
src/memu/database/inmemory/repositories/memory_item_repo.py	Dedup + salience retrieval
src/memu/database/postgres/repositories/memory_item_repo.py	Same for Postgres
src/memu/app/settings.py	Added ranking config, agent/session scoping
src/memu/client/__init__.py	NEW - Client wrapper module
src/memu/client/openai_wrapper.py	NEW - OpenAI wrapper implementation
tests/test_salience.py	NEW - 13 tests for salience features
tests/test_client_wrapper.py	NEW - 7 tests for client wrapper

Tests

• 20 tests total, all passing
• 13 tests for salience (hash, scoring, retrieval)
• 7 tests for client wrapper

Backward Compatibility

All features are opt-in. Default behavior unchanged.

Usage Examples

# Salience-aware retrieval
result = await service.retrieve(
    query="What does user like?",
    user={"user_id": "u1"},
    ranking="salience",  # Enable salience ranking
    recency_decay_days=30.0,
)

# Agent/session scoping
await service.memorize(
    resource_url="chat.json",
    modality="conversation",
    user={"user_id": "u1", "agent_id": "support-bot", "session_id": "sess123"},
)

# LLM client wrapper
from memu.client import wrap_openai
wrapped = wrap_openai(OpenAI(), service, user_id="u1")
response = wrapped.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "What's my favorite drink?"}]
)  # Memories auto-injected!

[evan-ak]

Hi, thank you very much for your contribution. We are actively working on merging this feature into MemU.

Given that there are multiple PRs introducing various kinds of fields to the memory item, and that some of them are exclusively used by specific memory types or applications, we’ve decided to consolidate these attributes into a single "extra" field to keep the memory item’s structure clear and concise.

At the same time, we want to ensure that this feature remains fully optional in the memorization and retrieval process, so we are about to implement a handy switch for it in the settings.

As a result, we are still working on a few minor revisions to the current commits and will proceed with the merge once these adjustments are complete.

Thanks again for the great work!