docs: add hybrid and keyword search references across documentation#264
docs: add hybrid and keyword search references across documentation#264
Conversation
Update all documentation and READMEs to consistently describe search as supporting semantic, keyword, and hybrid modes instead of only semantic. Changes: - Expand feature descriptions to include keyword and hybrid search - Add SDK usage examples (Python, TypeScript/JS, Java) for keyword and hybrid search modes - Add full-text indexing table to long-term memory docs - Fix deprecated function reference in agent examples - Fix tuple unpacking order in error handling example - Update search capability descriptions across all guides Context: The server already supports keyword (BM25) and hybrid (RRF) search modes via the search_mode parameter, but documentation only referenced semantic search. This brings docs in line with actual capabilities. Refs: #251, #253
🛡️ Jit Security Scan Results
✅ No security findings were detected in this PR
Security scan by Jit
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
@codex review |
There was a problem hiding this comment.
Pull request overview
Documentation-only update to align the project docs and SDK READMEs with the server’s existing support for semantic, keyword, and hybrid search modes, and to refresh examples to match current client APIs.
Changes:
- Expand documentation language to consistently describe semantic/keyword/hybrid search across guides and READMEs.
- Add keyword/hybrid search usage examples for TypeScript/JS and Java SDK docs (and Python client README).
- Update working-memory example code to use
get_or_create_working_memoryand correct tuple unpacking (created, memory).
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Updates feature list + architecture diagram text to mention semantic/keyword/hybrid search. |
| examples/README.md | Updates example feature description to include keyword/hybrid search. |
| docs/use-cases.md | Updates best-practice guidance to reference all search modes. |
| docs/typescript-sdk.md | Adds keyword + hybrid search examples for the TS SDK. |
| docs/README.md | Updates the feature matrix row label to include semantic/keyword/hybrid search modes. |
| docs/quick-start.md | Updates quick-start narrative bullets to mention all search modes. |
| docs/long-term-memory.md | Updates long-term memory overview and adds keyword/hybrid sections + examples. |
| docs/java-sdk.md | Adds keyword + hybrid search examples for the Java SDK. |
| docs/index.md | Updates landing-page bullets to mention semantic/keyword/hybrid search. |
| docs/agent-examples.md | Updates example descriptions and fixes working-memory example to use get_or_create_working_memory. |
| agent-memory-client/README.md | Updates working-memory example to get_or_create_working_memory and adds keyword/hybrid search examples. |
| agent-memory-client/agent-memory-client-js/README.md | Adds keyword/hybrid search examples and clarifies default search mode. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | Feature | REST API | MCP Server | CLI | Documentation | | ||
| |---------|----------|------------|-----|---------------| | ||
| | **Memory Search** | ✅ `/v1/long-term-memory/search` | ✅ `search_long_term_memory` | ❌ | [REST API](api.md), [MCP](mcp.md) | | ||
| | **Memory Search** (semantic, keyword, hybrid) | ✅ `/v1/long-term-memory/search` | ✅ `search_long_term_memory` | ❌ | [REST API](api.md), [MCP](mcp.md) | |
There was a problem hiding this comment.
The Feature Cross-Reference table marks CLI support for “Memory Search” as ❌, but the CLI does provide a agent-memory search command (see agent_memory_server/cli.py). Please update the CLI column to ✅ (and ideally link to the CLI search docs/section) so this matrix reflects actual capabilities.
| | **Memory Search** (semantic, keyword, hybrid) | ✅ `/v1/long-term-memory/search` | ✅ `search_long_term_memory` | ❌ | [REST API](api.md), [MCP](mcp.md) | | |
| | **Memory Search** (semantic, keyword, hybrid) | ✅ `/v1/long-term-memory/search` | ✅ `search_long_term_memory` | ✅ `agent-memory search` | [REST API](api.md), [MCP](mcp.md), [CLI](cli.md) | |
| MemoryServerError | ||
| ) | ||
|
|
||
| try: | ||
| memory = await client.get_working_memory("nonexistent-session") | ||
| except MemoryNotFoundError: | ||
| print("Session not found") | ||
| created, memory = await client.get_or_create_working_memory("nonexistent-session") |
There was a problem hiding this comment.
In this error-handling example, MemoryNotFoundError is still imported but is no longer used (the example now uses get_or_create_working_memory, which creates instead of raising not-found). Remove the unused import to avoid confusion for readers copying this snippet.
| - Messages - Semantic, keyword & hybrid search | ||
| - Structured memories - Topic modeling | ||
| - Summary of past messages - Entity recognition | ||
| - Metadata - Deduplication |
There was a problem hiding this comment.
The architecture diagram is inside a code block and uses spaced columns; removing the |- indentation on this line makes the first column start at column 1, which visually misaligns with the arrows above. Consider keeping the prior indentation (or using a consistent prefix like |-) so the two-column layout stays aligned and easier to read.
| - Messages - Semantic, keyword & hybrid search | |
| - Structured memories - Topic modeling | |
| - Summary of past messages - Entity recognition | |
| - Metadata - Deduplication | |
| |- Messages - Semantic, keyword & hybrid search | |
| |- Structured memories - Topic modeling | |
| |- Summary of past messages - Entity recognition | |
| |- Metadata - Deduplication |
| Long-term memory provides persistent storage that survives server restarts and session expiration. It's optimized for semantic, keyword, and hybrid search, deduplication, and rich metadata to enable intelligent retrieval of relevant information. | ||
|
|
||
| | Feature | Details | | ||
| |---------|---------| | ||
| | **Scope** | Cross-session, persistent | |
There was a problem hiding this comment.
The updated overview/table emphasize keyword + hybrid search and full-text indexing, but the “Characteristics” list immediately below still says “Vector Indexed: Semantic search …”, which now reads as semantic-only. Consider updating that bullet to be search-mode-agnostic (or explicitly mention full-text + hybrid support) for internal consistency on this page.
|
Codex Review: Didn't find any major issues. Swish! ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| MemoryServerError | ||
| ) | ||
|
|
||
| try: | ||
| memory = await client.get_working_memory("nonexistent-session") | ||
| except MemoryNotFoundError: | ||
| print("Session not found") | ||
| created, memory = await client.get_or_create_working_memory("nonexistent-session") |
There was a problem hiding this comment.
In this error-handling snippet, MemoryNotFoundError (and MemoryValidationError) are imported but not used, and MemoryNotFoundError is no longer applicable to the shown get_or_create_working_memory() call (it creates the session instead of raising not-found). Please either remove the unused imports or adjust the example to demonstrate the exceptions being imported.
|
|
||
| # Get only the 3 most recent messages | ||
| memory = await client.get_working_memory( | ||
| created, memory = await client.get_or_create_working_memory( |
There was a problem hiding this comment.
The example now unpacks created, memory = ... but never uses created. For clarity in docs (and to avoid encouraging unused variables), consider naming it _created/_ or adding a brief note/branch showing how to handle the created flag.
| created, memory = await client.get_or_create_working_memory( | |
| _created, memory = await client.get_or_create_working_memory( |
Summary
Update all documentation and READMEs to consistently describe search as supporting semantic, keyword, and hybrid modes instead of only semantic.
This is Part 1 of 2 PRs split from #251 to make review easier. This PR contains only documentation changes. Part 2 (core fix + MCP) builds on this branch.
Changes
get_working_memorytoget_or_create_working_memory)Files Changed (12)
README.mddocs/README.md,docs/index.md,docs/long-term-memory.md,docs/quick-start.md,docs/use-cases.md,docs/java-sdk.md,docs/typescript-sdk.md,docs/agent-examples.mdexamples/README.mdagent-memory-client/README.md,agent-memory-client/agent-memory-client-js/README.mdContext
The server already supports keyword (BM25) and hybrid (RRF) search modes via the
search_modeparameter, but documentation only referenced semantic search. This brings docs in line with actual capabilities.Per discussion on #251 (@vishal-bala, @abrookins, @tylerhutcherson, @nkanu17): MCP documentation for search modes is in Part 2 alongside the code changes, since MCP docs should stay coupled with the MCP implementation.
Review Notes
docs/mcp.mdchanges are intentionally in Part 2Refs: #251 (superseded by this PR and #265), #253 (tracking issue for remaining MCP/REST gaps)
Note
Low Risk
Low risk because changes are documentation/examples only; main risk is minor confusion if examples or parameter names don’t match released SDK/server behavior.
Overview
Updates docs and READMEs to consistently describe long-term memory search as supporting
semantic(default),keyword, andhybridmodes (includinghybrid_alpha) instead of only semantic search.Adds/updates SDK examples (Python, JS/TS, Java) to show
search_mode/searchModeusage for keyword and hybrid search, and refreshes examples to useget_or_create_working_memory(including corrected tuple unpacking / “created” handling) rather thanget_working_memory.Written by Cursor Bugbot for commit 8095f77. This will update automatically on new commits. Configure here.