OB1-inspired features: recency-boosted search + companion prompt packs

[imonroe]

Summary

First batch of improvements adapted from a review of the OB1 / Open Brain project (see the feature backlog issues #48–#56). These are the highest-value / lowest-effort, fully-verifiable items; each is self-contained and ships with tests and docs.

1. Opt-in recency-boosted search ranking (closes #53)

Search — both POST /api/v1/memories/search and the MCP search_memories tool — can now blend mem0's semantic similarity with a recency decay via an optional recency_weight (0.0–1.0).

• Defaults to 0 → no-op: existing search behavior is completely unchanged.
• Similarity scores are min-max normalized across the result set so the two signals are comparable.
• Items without a usable timestamp are never boosted.
• REST also exposes recency_half_life_days (default 30); when recency_weight > 0 each result carries a rerank_score for transparency.
• New app/ranking.py::rerank_by_recency(); wired into app/rest.py and app/mcp_server.py.

2. Companion prompt packs (closes #56)

Documentation-only reusable prompt packs under docs/prompts/ that drive the existing six MCP tools for recurring tasks, adapted from OB1's "skill packs":

• auto-capture.md — save a structured session summary at session end
• research-synthesis.md — findings with confidence levels + open questions
• meeting-synthesis.md — decisions, action items, risks
• Cross-linked from the User Guide's memory-prompting section.

Architecture notes

• No invariants touched: single Memory per process, MCP reads remain unscoped by agent_id, no new storage. Recency re-ranking is pure post-processing on the already-returned result set.

Tests

• New tests/test_ranking.py (10 cases: weight=0 no-op, recency promotion, similarity-dominant at low weight, missing/unparseable/metadata/updated_at timestamps, non-dict passthrough, single-item).
• Added REST cases (default no-rerank, rerank, out-of-range rejected) and MCP cases (param exposed, invocation).
• Full suite: 88 passed, ruff check clean.

Not included here (and why)

From the backlog, these are higher-effort or need validation against a live Qdrant (mem0 abstracts the payload layer), so they're deliberately deferred to follow-up PRs rather than shipped unverified:

• Data import toolkit: bulk-load existing data (ChatGPT, Obsidian, Readwise, X/Twitter, Gmail, etc.) via REST #49 Data import toolkit (high value; substantial, self-contained — good candidate for its own PR)
• Content-fingerprint dedup on the write path (cheap hash dedup before mem0 extraction) #48 Content-fingerprint dedup, Provenance & review-status metadata convention (governed "agent memory") #52 provenance metadata, Keyword / substring (trigram-style) search fallback alongside vector search #54 keyword search — need a live-Qdrant validation pass
• Support local Ollama embeddings + LLM provider (cost-free, private, no external API dependency) #51 Ollama embeddings — deprioritized per maintainer (staying on OpenAI for now)

https://claude.ai/code/session_017835DVrvURaYnbQiPQwzue

---

Generated by Claude Code

[Copilot]

Pull request overview

Adds opt-in, post-processing recency re-ranking to memory search results (REST + MCP) and introduces documentation-only “companion prompt packs” to help users drive the existing MCP tools more effectively.

Changes:

• Implement rerank_by_recency() to blend normalized similarity with a recency decay when recency_weight > 0.
• Expose recency_weight (and REST-only recency_half_life_days) via REST /memories/search and the MCP search_memories tool.
• Add docs/prompts/ prompt-pack docs and cross-link them from the User Guide.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
app/rest.py	Adds recency_weight + recency_half_life_days to REST search request and applies re-ranking post-search.
app/ranking.py	New re-ranking implementation (timestamp parsing + blended scoring + in-place result sorting).
app/mcp_server.py	Exposes recency_weight on MCP search_memories and applies re-ranking post-search.
tests/test_rest.py	Adds REST tests for default no-op behavior, rerank behavior, and range validation.
tests/test_ranking.py	Adds focused unit tests for reranking behavior and edge cases.
tests/test_mcp.py	Verifies MCP tool schema exposes recency_weight and that search invocation still scopes correctly.
docs/USER_GUIDE.md	Documents optional recency boost and links to new prompt packs.
docs/DEVELOPER_GUIDE.md	Documents the new app/ranking.py module in the architecture overview.
docs/prompts/README.md	Introduces prompt-pack concept and usage guidance.
docs/prompts/auto-capture.md	Adds an “auto-capture” session-summary prompt pack.
docs/prompts/research-synthesis.md	Adds a research-synthesis prompt pack.
docs/prompts/meeting-synthesis.md	Adds a meeting-synthesis prompt pack.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.