Claude Context & Memory Integrations
Relevant source files
The following files were used as context for generating this wiki page:
The Claude Context and Memory Integrations provide the flext-quality platform with capabilities for semantic code search, codebase indexing, and cross-session memory persistence. These integrations utilize the Model Context Protocol (MCP) to communicate with external servers, specifically claude-context for code-related operations and claude-mem for observation-based memory.
The system uses specialized clients to build tool calls and command-line instructions for the mcp-cli utility. These clients enable AI agents and automated workflows to retrieve relevant code snippets, track development history through timelines, and query stored observations to maintain context across different sessions.
Sources: src/flext_quality/integrations/claude_context.py:1-12, src/flext_quality/integrations/claude_mem.py:1-12, AGENTS.md:14-25
Architecture and Tool Flow
The integration architecture relies on a layered approach where high-level clients generate structured requests that are eventually transformed into executable shell commands for the MCP CLI.
The diagram shows the relationship between the high-level MCP tools, the specific integration clients for Context and Memory, and the base MCP client that communicates with the system CLI.
Sources: src/flext_quality/mcp/tools.py:24-64, src/flext_quality/integrations/claude_context.py:22-26, src/flext_quality/integrations/claude_mem.py:23-27
Claude Context Integration
The FlextQualityClaudeContextClient manages interactions with the claude-context MCP server. It provides three primary functionalities: indexing a codebase, searching for code semantically, and checking the current indexing status.
Core Context Functions
- Indexing:
build_index_callcreates a request to index a specific path or the current directory. - Searching:
build_search_callconstructs a semantic search query with a configurable result limit. - Status:
build_status_callretrieves the progress of ongoing indexing operations.
| Function | Tool Name | Description |
|---|---|---|
build_index_call | index_codebase | Triggers indexing of the codebase at a given path. |
build_search_call | search_code | Performs semantic search across the indexed codebase. |
build_status_call | get_indexing_status | Returns the current state of the indexer. |
Sources: src/flext_quality/integrations/claude_context.py:29-71, tests/unit/test_integrations.py:133-158
Claude Memory Integration
The FlextQualityClaudeMemClient facilitates cross-session memory by interacting with the claude-mem server. It allows the system to store and retrieve "observations" and view development events in a linear timeline.
Memory Retrieval Patterns
The client implements three patterns for accessing memory:
- Direct Lookup: Retrieving specific observations by their unique integer IDs.
- Semantic Search: Searching for relevant observations based on a text query.
- Timeline View: Retrieving events surrounding a specific "anchor" observation to understand temporal context.
The sequence diagram illustrates how a memory search request propagates from an AI agent through the tools and clients to generate a command.
Sources: src/flext_quality/integrations/claude_mem.py:30-74, src/flext_quality/mcp/tools.py:24-44
Data Models
The integrations use structured Pydantic models to ensure type safety for MCP requests and responses. These models define the contract for tool invocations and the expected data structure of the results.
Tool Call and Result Models
McpToolCall: Captures theservername, thetoolto execute, and a mapping ofparams.McpToolResult: Represents the output of an execution, including asuccessflag, adatamapping, and an optionalerrormessage.
# src/flext_quality/_models/flextqualitymodels_part_02.py
class McpToolCall(_WebModels.ManagedModel):
server: str = _WebModels.Field(description="Identifier of the MCP server...")
tool: str = _WebModels.Field(description="Name of the MCP tool...")
params: t.JsonMapping = _WebModels.Field(default_factory=dict, description="Parameters...")
class McpToolResult(_WebModels.ManagedModel):
success: bool = _WebModels.Field(description="Whether the tool completed successfully.")
data: t.StrMapping | None = _WebModels.Field(default=None)
error: str | None = _WebModels.Field(default=None)
Sources: src/flext_quality/_models/flextqualitymodels_part_02.py:716-749
MCP Tools Interface
The FlextQualityMcpTools class exposes these integrations as static methods decorated for the MCP server. These methods normalize the results from the clients into a standard t.JsonMapping format suitable for transport.
Exposed Tool Methods
search_memory: UsesFlextQualityClaudeMemClientto find observations. It defaults to a search limit defined in the project constants.search_code: UsesFlextQualityClaudeContextClientto search source files. It returns both the structured tool call parameters and the raw shell command for execution.
Sources: src/flext_quality/mcp/tools.py:24-64, tests/unit/test_integrations.py:165-185
Validation and Health Checks
Both integration clients provide a health_check method to verify the availability of the required MCP servers and the mcp-cli utility.
- The client checks if
mcp-cliis present in the system PATH. - It generates a status report containing the
servername and connection state (connectedordisconnected). - If a custom
timeout_msis configured, it is included in the health check payload.
Sources: src/flext_quality/integrations/claude_context.py:91-100, src/flext_quality/integrations/claude_mem.py:109-115, tests/unit/test_integrations.py:44-65
Summary
The Claude Context & Memory Integrations act as the bridge between the flext-quality orchestration layer and the Model Context Protocol ecosystem. By providing dedicated clients for claude-context and claude-mem, the system enables advanced agentic features such as semantic code awareness and persistent cross-session knowledge. These tools are implemented with strict type safety using Pydantic models and are verified through contract tests that exercise the generation of CLI commands and the parsing of JSON results.