+
📖 指标定义和说明
-
+
"""
for metric_key, info in metrics_info.items():
if metric_key in overall:
html_content += f"""
-
-
{info["name"]}
-
-
类别: {info["category"]}
-
说明: {info["description"]}
+
+
{info["name"]}
+
+
类别: {info["category"]}
+
说明: {info["description"]}
+
-
"""
html_content += """
+
-
-
"""
# 页脚
diff --git a/litho.docs/1.Overview.md b/litho.docs/1.Overview.md
index dd84451..f5f5bf7 100644
--- a/litho.docs/1.Overview.md
+++ b/litho.docs/1.Overview.md
@@ -1,9 +1,7 @@
# System Context Overview
-**Document Generated on:** 2025-12-18 03:27:26 (UTC) (UTC)
-**Timestamp:** 1766028446
-**System:** `cortex-mem` – AI Agent Memory Management System
-**Architecture Level:** C4 Model – System Context (Level 1)
+**Generated on:** 2025-12-30 11:17:28 (UTC)
+**Timestamp:** 1767093448
---
@@ -13,181 +11,166 @@
**cortex-mem**
### Project Description
-`cortex-mem` is a full-stack memory management system designed specifically for AI agents. It enables persistent, semantically searchable, and optimizable storage of experiential knowledge (referred to as "memories") that AI agents accumulate during interactions. The system supports long-term context retention, enhancing agent consistency, reasoning, and intelligence across sessions.
+*cortex-mem* is a full-stack memory management system designed to provide AI agents with persistent, searchable, and optimizable memory storage. It enables intelligent agents to retain context across interactions by storing conversation history, procedural knowledge, and factual information in a structured and semantically accessible format.
-At its core, `cortex-mem` leverages vector embeddings and large language models (LLMs) to store, retrieve, and refine memories based on semantic meaning rather than exact keyword matches. It provides advanced capabilities such as deduplication, relevance scoring, memory optimization, and analytics through a modular architecture.
+The system supports multiple access interfaces—including CLI, HTTP API, MCP (Memory Control Protocol), and a web-based dashboard—allowing seamless integration into diverse AI agent architectures and operational workflows. By leveraging vector embeddings and Large Language Models (LLMs), *cortex-mem* delivers advanced semantic search, intelligent memory classification, and automated optimization capabilities.
### Core Functionality
-- **Memory CRUD Operations**: Create, read, update, and delete memories with rich metadata.
-- **Semantic Search**: Retrieve relevant memories using natural language queries via vector similarity search.
-- **Memory Optimization**: Automatically detect and resolve issues like redundancy, low quality, or irrelevance using LLM-driven analysis.
-- **Analytics & Insights**: Visualize memory usage patterns, performance metrics, and optimization outcomes via a dashboard.
-- **Multi-Interface Access**: Support for REST API, CLI, and MCP protocol for integration flexibility.
-- **Evaluation Framework**: Built-in tools for benchmarking recall accuracy, search effectiveness, and system performance.
+- **Persistent Memory Storage**: Long-term retention of agent memories with metadata and semantic context.
+- **Semantic Search**: Retrieve relevant memories using natural language queries via vector similarity.
+- **Memory Optimization**: Automatically detect and resolve issues such as duplication, irrelevance, or redundancy.
+- **Multi-Interface Access**: Support for developers, agents, and operators through CLI, REST API, MCP, and web UI.
+- **Configurable & Extensible**: Centralized configuration enables consistent behavior across deployment environments.
### Business Value
-`cortex-mem` significantly enhances the cognitive capabilities of AI agents by providing reliable, scalable, and intelligent memory infrastructure. This enables:
-- Improved continuity and personalization in agent-user interactions.
-- Higher fidelity in decision-making through access to historical context.
-- Operational visibility into agent memory health and evolution.
-- Accelerated development and evaluation of memory-augmented AI systems.
+*cortex-mem* enhances the intelligence and continuity of AI agents by enabling them to:
+- Maintain contextual awareness across extended conversations and tasks.
+- Recall relevant past experiences efficiently.
+- Operate more autonomously through self-maintained memory quality.
+
+This results in improved user experience, higher task success rates, and reduced cognitive load on both agents and their human operators.
### Technical Characteristics
-- **Modular & Layered Architecture**: Clear separation between core logic, interfaces, and external dependencies.
-- **Vector-First Design**: Memories are stored and retrieved using high-dimensional embeddings in a dedicated vector database.
-- **LLM-Integrated Processing**: External LLM services are used for embedding generation and semantic understanding.
-- **Configurable & Extensible**: Supports TOML-based configuration and pluggable components for storage and LLM providers.
-- **Evaluation-Driven Development**: Includes tools for testing, benchmarking, and validating memory system behavior.
+- **Architecture Style**: Modular microservices with domain-driven design principles.
+- **Primary Languages**: Rust (backend/core logic), TypeScript (frontend/dashboard).
+- **Integration Model**: API-first, service-oriented with external dependencies on LLMs and vector databases.
+- **Deployment Target**: Cloud-native, containerizable services with minimal infrastructure coupling.
---
## 2. Target Users
-| User Role | Description | Key Needs | Usage Scenarios |
-|---------|-------------|-----------|----------------|
-| **AI Agent Developers** | Software engineers building AI-powered applications requiring persistent memory. |
- Integrate memory into agents via APIs
- Manage memories programmatically
- Ensure high recall and low latency in retrieval
|
- Building chatbots with long-term user context
- Developing autonomous agents that learn from experience
- Testing memory recall under various query conditions
|
-| **System Administrators** | Operations personnel managing AI infrastructure and monitoring system health. |
- Monitor memory usage and system performance
- Run optimization routines
- Inspect memory trends and anomalies
|
- Scheduling nightly memory deduplication
- Reviewing dashboard insights for capacity planning
- Responding to alerts about memory bloat or degradation
|
-| **Research Scientists** | Academics and researchers studying AI memory systems and agent cognition. |
- Benchmark memory retrieval accuracy
- Evaluate optimization efficacy
- Generate synthetic datasets for validation
|
- Comparing `cortex-mem` against other memory systems
- Studying the impact of memory quality on agent performance
- Designing experiments with controlled memory inputs
|
+The *cortex-mem* system serves three primary user roles, each with distinct needs and interaction patterns:
+
+| User Role | Description | Key Needs |
+|---------|-------------|-----------|
+| **AI Agents** | Intelligent software agents requiring persistent memory to maintain context across interactions. |
- Store conversation history
- Retrieve relevant memories based on current context
- Optimize memory usage for performance and relevance
|
+| **Developers** | Software engineers integrating *cortex-mem* into AI applications or agent frameworks. |
- Programmatic access via API or MCP
- Flexible configuration options
- Clear integration patterns with existing systems
|
+| **System Administrators** | Operators responsible for monitoring, maintaining, and tuning the memory infrastructure. |
- Real-time monitoring via dashboard
- Tools for memory optimization and maintenance
- Logging, alerting, and configuration management
|
-These user roles interact with the system through different entry points:
-- **Developers** use the REST API and CLI.
-- **Administrators** use the CLI and Insights Dashboard.
-- **Researchers** use the evaluation framework and API for data collection.
+### Usage Scenarios
+- An AI customer support agent recalls previous interactions with a user to provide personalized responses.
+- A developer integrates *cortex-mem* into an autonomous agent framework using the HTTP API for memory persistence.
+- An operator runs a nightly optimization job via CLI to deduplicate and clean memory entries.
+- A research team evaluates *cortex-mem* against alternative memory systems like *LangMem* for benchmarking purposes.
---
## 3. System Boundaries
### System Scope
-The `cortex-mem` system provides a complete, end-to-end solution for managing AI agent memories. It encompasses all aspects of memory lifecycle management, from ingestion and storage to search, optimization, and analysis.
+*cortex-mem* provides a dedicated memory management layer for AI agents. It handles the full lifecycle of memory data—including creation, retrieval, search, update, deletion, and optimization—through multiple standardized interfaces.
-> **Scope Statement**:
-> *The cortex-mem system provides a complete memory management solution for AI agents, including storage, retrieval, optimization, and analysis capabilities.*
+The system acts as a **middleware service**, decoupling memory logic from core agent intelligence, allowing it to be reused across different agent implementations.
### Included Components
-The following core components are within the system boundary:
+The following capabilities are within the scope of *cortex-mem*:
| Component | Description |
|--------|-------------|
-| **Memory CRUD Operations** | Full support for creating, reading, updating, and deleting memories with metadata tagging. |
-| **Semantic Search Engine** | Enables natural language search over stored memories using vector embeddings. |
-| **Memory Optimization Engine** | Detects duplicates, improves memory quality, and removes irrelevant entries using LLMs. |
-| **Insights & Analytics Dashboard** | Web-based UI for visualizing memory usage, trends, and optimization reports. |
-| **REST API Service** (`cortex-mem-service`) | HTTP interface for programmatic access to memory operations and system controls. |
-| **Command-Line Interface** (`cortex-mem-cli`) | Tool for local interaction, scripting, and administrative tasks. |
-| **MCP Protocol Adapter** (`cortex-mem-mcp`) | Enables integration with agent frameworks using the Memory Consistency Protocol. |
-| **Evaluation Framework** | Tools for testing recall, precision, latency, and optimization effectiveness. |
-| **Core Memory Engine** (`cortex-mem-core`) | Central module handling memory logic, vector integration, and LLM coordination. |
-| **Configuration Management** | Centralized configuration via TOML files supporting environment-specific settings. |
+| **Memory Storage & Retrieval** | CRUD operations for memory entries with rich metadata. |
+| **Semantic Search** | Vector-based similarity search using embeddings generated by LLMs. |
+| **Memory Optimization Engine** | Automated analysis and improvement of memory quality (e.g., deduplication, relevance filtering). |
+| **Multiple Access Interfaces** |
- CLI: For administrative and batch operations
- HTTP API: For programmatic integration
- MCP: For direct AI agent tool invocation
- Web Dashboard: For monitoring and visualization
|
+| **Web-Based Monitoring Dashboard** | Real-time insights into memory usage, performance metrics, and optimization results. |
+| **Configuration Management** | Centralized configuration system for all components (e.g., LLM endpoints, Qdrant settings). |
### Excluded Components
-The following are explicitly outside the scope of `cortex-mem`:
+The following are explicitly **outside** the scope of *cortex-mem*:
| Component | Reason for Exclusion |
|--------|------------------------|
-| **Core LLM Model Training** | The system consumes LLM APIs but does not train or fine-tune foundation models. |
-| **Vector Embedding Model Development** | Relies on external LLM services for embeddings; does not develop embedding models. |
-| **Operating System Resource Management** | Does not manage CPU, memory, or disk at the OS level. |
-| **Network Infrastructure Provisioning** | Assumes network connectivity is provided; does not handle networking setup or scaling. |
+| **Core AI Agent Logic** | *cortex-mem* does not implement agent reasoning, planning, or decision-making. It only provides memory services. |
+| **Application-Specific Business Rules** | Domain-specific logic (e.g., "remember user preferences only after consent") is handled by the agent, not *cortex-mem*. |
+| **User Interface Design for End Applications** | While a monitoring dashboard is provided, end-user UIs (e.g., chat interfaces) are outside scope. |
+| **Network Infrastructure Management** | Deployment, scaling, networking, and security of underlying infrastructure are managed externally. |
-This boundary ensures focus on memory-specific functionality while leveraging best-of-breed external services for AI processing and infrastructure.
+> ✅ **Boundary Principle**: *cortex-mem* focuses on **what** is remembered and **how** it is accessed, not **why** or **when** it should be used.
---
## 4. External System Interactions
-The `cortex-mem` system interacts with several external systems to deliver its functionality. These interactions are essential for storage, AI processing, and user access.
+*cortex-mem* integrates with several external systems to deliver its functionality. These interactions are essential for core operations such as embedding generation, vector storage, and benchmarking.
+
+### External Systems
-### External Systems List
+| System Name | Interaction Type | Description | Direction |
+|------------|------------------|-------------|----------|
+| **Qdrant** | Database Storage | Vector database used to store and retrieve memory embeddings. Enables high-performance semantic search through approximate nearest neighbor (ANN) indexing. | *cortex-mem* → Qdrant |
+| **OpenAI** | API Integration | LLM service used for:
- Generating text embeddings
- Extracting structured facts/entities
- Analyzing memory content for optimization
| *cortex-mem* → OpenAI |
+| **LangMem** | Benchmarking | Alternative memory system used for comparative evaluation and performance testing. Not integrated at runtime. | One-way analysis (no runtime dependency) |
-| External System | Interaction Type | Description | Direction |
-|----------------|------------------|-------------|----------|
-| **Qdrant** | Database Storage | Vector database used to store memory embeddings and enable semantic search. Memories are indexed by their vector representations for fast similarity lookup. | System → Qdrant (Write/Read) |
-| **LLM Services** (e.g., OpenAI, Anthropic, etc.) | API Integration | External language model APIs used to generate embeddings for memory content and queries. Also used during optimization to assess and rewrite memories. | System → LLM (Request/Response) |
-| **HTTP Clients** | User Interface | Web browsers and HTTP clients that access the Insights Dashboard and REST API. Includes developer tools, monitoring systems, and agent integrations. | Client → System |
-| **Command Line Interface (CLI)** | User Interface | Terminal applications used by developers and administrators to interact with the system via shell commands. | User → System |
+### Interaction Details
-### Dependency Analysis
+#### Qdrant Integration
+- **Purpose**: Persistent storage of vector embeddings and metadata.
+- **Protocol**: gRPC/HTTP (via Qdrant client SDK).
+- **Data Flow**:
+ - On memory creation: embedding vector + metadata → stored in Qdrant collection.
+ - On search: query embedding → similarity search → top-k results returned.
+- **Failure Impact**: Loss of semantic search capability; memory metadata may still be accessible via fallback mechanisms.
-| From | To | Type | Strength | Description |
-|------|----|------|----------|-------------|
-| `cortex-mem` → Qdrant | Service Dependency | 9.5 | Core persistence layer; all memory data is stored and retrieved via Qdrant’s vector search capabilities. |
-| `cortex-mem` → LLM Services | Service Call | 9.0 | Critical for embedding generation and memory optimization. System cannot function without access to LLM APIs. |
-| HTTP Clients → `cortex-mem` | User Interaction | 8.5 | Primary means for users to view analytics and trigger operations via dashboard or API. |
-| CLI Users → `cortex-mem` | User Interaction | 8.0 | Used for scripting, debugging, and administrative control. |
+#### OpenAI Integration
+- **Purpose**: Enable intelligent memory processing via LLM capabilities.
+- **Usage Patterns**:
+ - Embedding generation (`text-embedding-ada-002` or equivalent).
+ - Structured extraction (e.g., "extract entities from this conversation").
+ - Memory analysis (e.g., "are these two memories duplicates?").
+- **Protocol**: HTTPS REST API.
+- **Failure Impact**: Degraded functionality in memory creation, search, and optimization; system may fall back to cached embeddings or skip enrichment.
-> **Note**: All external dependencies are abstracted behind interfaces in `cortex-mem-core`, allowing for future pluggability (e.g., switching from Qdrant to Pinecone or Weaviate).
+#### LangMem (Benchmarking)
+- **Purpose**: Used in evaluation workflows to compare *cortex-mem*’s performance (latency, recall, precision) against alternative memory systems.
+- **Interaction**: Offline comparison scripts; no runtime coupling.
+- **Impact**: No operational dependency; used solely for R&D and validation.
---
## 5. System Context Diagram
-### C4 Model – System Context (Level 1)
+Below is a **C4 Model - Level 1: System Context** diagram representing *cortex-mem* and its relationships with users and external systems.
-Below is a Mermaid-formatted diagram representing the **System Context** view of `cortex-mem`. This diagram illustrates the system as a single container and its relationships with external entities.
+### Mermaid Diagram (System Context)
```mermaid
C4Context
title System Context Diagram for cortex-mem
- Person(developer, "AI Agent Developer", "Builds AI agents that require persistent memory. Uses API and CLI.")
- Person(admin, "System Administrator", "Manages system health, runs optimizations, monitors usage.")
- Person(researcher, "Research Scientist", "Evaluates memory performance, runs benchmarks, analyzes data.")
+ Person(ai_agent, "AI Agent", "Intelligent software agent requiring persistent memory")
+ Person(developer, "Developer", "Engineer integrating memory into AI applications")
+ Person(admin, "System Administrator", "Operator managing memory infrastructure")
- System(cortex_mem, "cortex-mem", "Memory management system for AI agents with semantic search, optimization, and analytics.")
+ System(cortex_mem, "cortex-mem", "Memory management system for AI agents\nProvides persistent, searchable, and optimizable memory storage")
- System_Ext(qdrant, "Qdrant", "Vector database for storing and retrieving memory embeddings.")
- System_Ext(llm_services, "LLM Services", "External APIs for generating embeddings and improving memory quality (e.g., OpenAI, Anthropic).")
- System_Boundary(http_clients, "HTTP Clients") {
- System_Ext(browser, "Web Browser", "Accesses insights dashboard and REST API.")
- }
- System_Boundary(cli, "CLI Environment") {
- System_Ext(terminal, "Terminal", "Runs cortex-mem-cli commands.")
- }
+ System_Ext(qdrant, "Qdrant", "Vector database for embedding storage and semantic search")
+ System_Ext(openai, "OpenAI", "LLM service for embeddings, text generation, and analysis")
+ System_Ext(langmem, "LangMem", "Alternative memory system used for benchmarking")
- Rel(developer, cortex_mem, "Uses API and CLI to manage agent memories")
- Rel(admin, cortex_mem, "Monitors via dashboard, runs optimization via CLI")
- Rel(researcher, cortex_mem, "Runs evaluations, extracts data via API")
+ Rel(ai_agent, cortex_mem, "Uses memory via MCP or API", "JSON/HTTP, MCP Protocol")
+ Rel(developer, cortex_mem, "Integrates via API/CLI", "REST API, CLI Commands")
+ Rel(admin, cortex_mem, "Monitors & manages via dashboard", "Web UI, CLI")
- Rel(cortex_mem, qdrant, "Stores and retrieves vector embeddings via gRPC/HTTP")
- Rel(cortex_mem, llm_services, "Sends text to generate embeddings and optimize memories")
- Rel(cortex_mem, browser, "Serves web UI and accepts API requests over HTTPS")
- Rel(cortex_mem, terminal, "Accepts command-line input and returns output")
-
- UpdateLayoutConfig($c4ShapeInRow="2", $c4BoundaryInRow="2")
+ Rel(cortex_mem, qdrant, "Stores/retrieves vectors", "gRPC/HTTP")
+ Rel(cortex_mem, openai, "Requests embeddings & analysis", "HTTPS API")
+ Rel_R(cortex_mem, langmem, "Benchmarked against", "Offline evaluation")
```
### Key Interaction Flows
1. **Memory Creation Flow**
- - Developer sends `POST /memories` via HTTP client.
- - `cortex-mem` uses LLM service to generate embedding.
- - Stores memory + embedding in Qdrant.
- - Returns memory ID.
-
-2. **Semantic Search Flow**
- - User submits natural language query via API or CLI.
- - Query is embedded using LLM service.
- - Vector search performed in Qdrant.
- - Results filtered and ranked by `cortex-mem-core`, returned to user.
-
-3. **Optimization Flow**
- - Admin triggers `/optimization/start`.
- - System analyzes memories for duplicates and quality issues.
- - LLM rewrites or merges low-quality entries.
- - Updated memories stored back in Qdrant.
- - Report generated and accessible via dashboard.
-
-4. **Insights Access Flow**
- - Browser requests dashboard page.
- - `cortex-mem-insights` fetches memory statistics and optimization history.
- - Renders charts and tables showing memory growth, search success rate, etc.
-
-### Architecture Decisions Reflected
-- **Single System Boundary**: All components (`core`, `service`, `cli`, `insights`) are treated as one cohesive system.
-- **Externalized AI & Storage**: LLMs and vector DBs are external systems, emphasizing cloud-native integration.
-- **Multi-Channel Access**: Supports both machine (API) and human (CLI, UI) interaction patterns.
-- **No Direct User-to-Database Access**: All data flows through `cortex-mem`, ensuring consistency and security.
+ - User/AI agent → CLI/API/MCP → *cortex-mem* → OpenAI (embedding) → Qdrant (storage)
+ - Metadata and extracted facts are stored alongside the vector.
+
+2. **Memory Retrieval Flow**
+ - Query → *cortex-mem* → OpenAI (query embedding) → Qdrant (similarity search) → Ranked results → User/Agent
+
+3. **Memory Optimization Flow**
+ - Admin triggers optimization → *cortex-mem* analyzes memory collection → Uses OpenAI to assess similarity → Executes merge/delete → Reports via dashboard
+
+4. **Monitoring & Configuration**
+ - Admin uses web dashboard to view memory stats, run optimizations, and adjust configuration.
+ - All components read from centralized config (e.g., `config.toml`).
---
@@ -195,60 +178,69 @@ C4Context
### Main Technology Stack
-| Layer | Technology | Purpose |
-|------|-----------|--------|
-| **Core Engine** | Rust (`cortex-mem-core`) | High-performance, memory-safe implementation of memory logic. |
-| **API Service** | Rust + Axum (`cortex-mem-service`) | RESTful HTTP server with async support. |
-| **CLI Tool** | Rust + Clap (`cortex-mem-cli`) | Cross-platform command-line interface. |
-| **Vector Database** | Qdrant | Persistent, scalable vector storage with semantic search. |
-| **LLM Integration** | OpenAI API, Anthropic, or compatible | Embedding generation and memory refinement. |
-| **Frontend (Insights)** | TypeScript + React | Interactive dashboard for analytics and reporting. |
-| **Configuration** | TOML | Human-readable, version-controllable config files. |
-| **Protocol Support** | MCP (Memory Consistency Protocol) | Standardized interface for agent memory synchronization. |
+| Layer | Technology | Rationale |
+|------|-----------|---------|
+| **Backend Core** | Rust | High performance, memory safety, ideal for systems-level logic and LLM integration. |
+| **Frontend Dashboard** | TypeScript (SvelteKit) | Reactive UI framework for real-time monitoring and interaction. |
+| **Vector Database** | Qdrant | Efficient ANN search, strong filtering support, gRPC/HTTP API. |
+| **LLM Provider** | OpenAI | Industry-standard embeddings and structured output capabilities. |
+| **Configuration** | TOML + Environment Variables | Human-readable, hierarchical, and deployable across environments. |
+| **Interfaces** |
- CLI: Rust (Clap)
- HTTP API: Axum (Rust)
- MCP: Custom protocol over JSON-RPC
- Web: Svelte + REST
| Multiple entry points for different user types and integration needs. |
### Architecture Patterns
-| Pattern | Application in `cortex-mem` |
-|--------|----------------------------|
-| **Layered Architecture** | Clear separation: Core Logic → Service Layer → Interface Layer (API/CLI/Dashboard). |
-| **Plugin Abstraction** | LLM clients and vector stores implement traits/interfaces for easy swapping. |
-| **Event-Driven Orchestration** | Optimization workflows are triggered and progress asynchronously. |
-| **Configuration-Driven Behavior** | System behavior (e.g., embedding model, thresholds) is defined in TOML. |
-| **Evaluation-First Design** | Built-in tools allow continuous validation of memory recall and quality. |
-
-### Key Design Decisions
+#### Modular Microservices Architecture
+- **Separation of Concerns**: Each domain (e.g., Memory Management, LLM Integration) is encapsulated with clear responsibilities.
+- **Shared Core Library**: `cortex-mem-core` contains business logic reused across CLI, API, MCP, and dashboard services.
+- **Frontend-Backend Decoupling**: Web dashboard communicates via RESTful APIs to backend services.
-1. **Rust as Primary Language**
- - Chosen for memory safety, performance, and concurrency—critical for systems handling large-scale data and real-time queries.
+#### Domain-Driven Design (DDD)
+The system is organized into well-defined domains:
-2. **Vector Database Abstraction**
- - The `vector_store` module abstracts Qdrant behind a trait, enabling future support for alternative backends (e.g., Chroma, FAISS).
+| Domain | Type | Responsibility |
+|-------|------|----------------|
+| **Memory Management Domain** | Core Business | Memory lifecycle, search, classification |
+| **Memory Optimization Domain** | Core Business | Quality analysis, deduplication, plan execution |
+| **LLM Integration Domain** | Core Business | Embedding generation, content extraction, intelligence |
+| **Storage Integration Domain** | Infrastructure | Qdrant interaction, vector persistence |
+| **Access Interface Domain** | Tool Support | CLI, API, MCP, Web UI |
+| **Configuration Management Domain** | Infrastructure | Centralized settings for all components |
-3. **LLM as a Service**
- - Avoids coupling to any single provider; supports multiple LLM APIs through a unified client interface.
+#### Key Design Decisions
-4. **Unified Core Module**
- - `cortex-mem-core` encapsulates all business logic, ensuring consistent behavior across API, CLI, and dashboard.
+| Decision | Rationale | Impact |
+|--------|---------|--------|
+| **Rust for Core Logic** | Ensures performance, safety, and concurrency for high-throughput memory operations. | Enables low-latency responses even under heavy load. |
+| **Multiple Access Interfaces** | Supports diverse use cases: agents (MCP), developers (API), operators (CLI/Web). | Increases adoption and integration flexibility. |
+| **Centralized Configuration** | Single source of truth for LLM keys, Qdrant URLs, optimization thresholds. | Simplifies deployment and reduces misconfiguration risk. |
+| **Vector + Metadata Hybrid Storage** | Combines semantic search (vector) with precise filtering (metadata). | Delivers accurate and contextually relevant results. |
+| **LLM-Driven Intelligence** | Leverages LLMs not just for embeddings but also for fact extraction and decision logic. | Enables smarter memory management beyond keyword matching. |
-5. **Separation of Concerns**
- - Each domain (Memory Management, Storage, Optimization, Insights) has well-defined responsibilities and minimal overlap.
+### Cross-Domain Dependencies
-6. **Extensible Evaluation Framework**
- - Allows developers and researchers to define custom test suites for memory recall, search accuracy, and optimization impact.
+```mermaid
+graph TD
+ A[Access Interface Domain] -->|Calls| B(Memory Management Domain)
+ B -->|Uses| C[LLM Integration Domain]
+ B -->|Stores to| D[Storage Integration Domain]
+ C -->|Config from| E[Configuration Management Domain]
+ D -->|Config from| E
+ F[Memory Optimization Domain] -->|Analyzes & Updates| B
+ F -->|Config from| E
+ A -->|Config from| E
+```
-7. **TOML-Based Configuration**
- - Enables declarative setup of system parameters (e.g., embedding dimensions, optimization thresholds, API keys).
+> 🔗 **Dependency Strength Summary**:
+> - Strongest: Access Interface → Memory Management (9.5)
+> - Critical: Memory Management → Storage Integration (9.0)
+> - Important: All domains → Configuration Management (7.0–8.5)
---
## Conclusion
-The `cortex-mem` system represents a robust, production-ready memory management platform tailored for AI agents. Its **System Context** clearly defines its role within the broader ecosystem: a centralized, intelligent memory store that integrates with vector databases and LLMs to provide persistent, searchable, and self-improving knowledge retention.
-
-By adhering to the C4 model’s System Context level, this document establishes a shared understanding across stakeholders—developers, operators, and researchers—of what the system does, who uses it, how it interacts with the outside world, and what lies within its architectural boundaries.
-
-This foundation enables informed decision-making for future development, integration, and operational planning.
+The *cortex-mem* system establishes a robust, extensible foundation for AI agent memory management. By clearly defining its boundaries, user roles, and external integrations, it serves as a reliable middleware component in modern AI architectures.
----
+Its modular design, multi-interface support, and intelligent use of LLMs and vector databases make it suitable for both research and production environments. The system enables AI agents to evolve from stateless responders to context-aware, learning entities—paving the way for more autonomous and effective artificial intelligence.
-**End of Document**
\ No newline at end of file
+This C4 System Context document provides a comprehensive view of *cortex-mem*’s role in the ecosystem, serving as a reference for architects, developers, and operators involved in its deployment and extension.
\ No newline at end of file
diff --git a/litho.docs/2.Architecture.md b/litho.docs/2.Architecture.md
index bb089c2..f942bcd 100644
--- a/litho.docs/2.Architecture.md
+++ b/litho.docs/2.Architecture.md
@@ -1,7 +1,7 @@
# System Architecture Documentation
**Project:** `cortex-mem`
-**Generated at:** 2025-12-18 03:29:11 (UTC) (UTC)
-**Timestamp:** 1766028551
+**Generated on:** 2025-12-30 11:19:34 (UTC)
+**Timestamp:** 1767093574
---
@@ -9,44 +9,31 @@
### Architecture Design Philosophy
-The **cortex-mem** system is designed around the principles of **modularity**, **extensibility**, and **intelligent automation**, with a strong emphasis on enabling **AI agents to maintain persistent, searchable, and optimizable knowledge** across interactions. The architecture follows a **layered, domain-driven design (DDD)** approach, where core business logic is encapsulated in a central engine (`cortex-mem-core`), while multiple interface layers provide flexible access for developers, operators, and researchers.
+The `cortex-mem` system is designed around the principle of **persistent, intelligent memory management for AI agents**, enabling them to retain context across interactions and improve decision-making over time. The architecture emphasizes **modularity, extensibility, and interoperability**, ensuring that diverse integration scenarios—from CLI tools to agent frameworks—can coexist seamlessly.
-The system embraces **separation of concerns** through well-defined boundaries between:
-- **Core memory processing**
-- **Storage and retrieval**
-- **User-facing interfaces**
-- **Analytics and evaluation**
+At its core, the system follows a **microservices-inspired modular monolith pattern**, where core business logic is centralized in a shared Rust-based library (`cortex-mem-core`), while multiple access interfaces (CLI, HTTP API, MCP, Web UI) operate as independent but tightly integrated components. This design balances performance and maintainability with flexibility and scalability.
-This modular structure ensures that each component can evolve independently, supporting both research experimentation and production deployment.
-
----
+The system leverages **external AI and vector storage services** (OpenAI and Qdrant) to offload computationally intensive tasks such as embedding generation and semantic search, allowing the core engine to focus on orchestration, optimization, and lifecycle management.
### Core Architecture Patterns
-| Pattern | Application | Benefit |
-|-------|------------|--------|
-| **Modular Monolith / Plugin Architecture** | Core engine exposes pluggable traits (`VectorStore`, `LLMClient`, etc.) | Enables extensibility without tight coupling |
-| **Strategy Pattern** | Used for detectors, evaluators, and optimizers | Allows runtime selection of algorithms based on configuration |
-| **Shared State Pattern** | `Arc
` shared across API handlers | Thread-safe access to core engine in async environment |
-| **Command-Query Responsibility Segregation (CQRS)** | Separation of write (CRUD) and read (search/analysis) paths | Optimized data flow for different use cases |
-| **Event-Driven Orchestration (Implicit)** | Optimization workflows trigger analysis → planning → execution | Supports complex, multi-stage processes |
-
----
+- **Layered Architecture**: Clear separation into access, business logic, infrastructure, and support layers.
+- **Modular Monolith with Shared Core**: All interfaces share a common core engine, reducing duplication and ensuring consistency.
+- **Event-Driven Orchestration**: Workflows are initiated by user or agent requests and orchestrated through a centralized memory manager.
+- **Configuration-Driven Behavior**: A centralized configuration system (`cortex-mem-config`) ensures uniform behavior across all components.
+- **LLM-Augmented Intelligence**: LLMs are used not just for embeddings, but also for content analysis, fact extraction, and optimization decisions.
### Technology Stack Overview
-| Layer | Technology | Rationale |
-|------|-----------|---------|
-| **Core Engine** | Rust | Memory safety, performance, async support, trait-based abstraction |
-| **REST API** | Axum (Rust) | Lightweight, type-safe, integrates seamlessly with Tokio |
-| **CLI Interface** | Clap (Rust) | Declarative argument parsing, rich CLI experience |
-| **Web Dashboard** | SvelteKit + Elysia.js | Fast frontend, minimal boilerplate, TypeScript safety |
-| **Vector Database** | Qdrant | High-performance semantic search, metadata filtering, cloud-native |
-| **LLM Integration** | OpenAI-compatible APIs via RIG | Flexibility to use various LLM providers (OpenAI, Anthropic, local models) |
-| **Configuration** | TOML | Human-readable, hierarchical, widely supported |
-| **Runtime** | Tokio | Asynchronous execution model for high concurrency |
-
-> ✅ **Key Insight**: The choice of **Rust** as the primary language reflects a focus on **performance, reliability, and safety**—critical for systems handling persistent agent memory where data integrity and low-latency operations are essential.
+| Layer | Technology | Purpose |
+|------|-----------|--------|
+| **Core Engine** | Rust | High-performance, memory-safe backend logic |
+| **Interfaces** | Rust (CLI, API, MCP), TypeScript/Svelte (Web UI) | Multi-channel access |
+| **Storage** | Qdrant (Vector DB) | Semantic search via embeddings |
+| **AI Services** | OpenAI API | Embedding generation, content analysis, structured extraction |
+| **Configuration** | TOML | Human-readable, hierarchical configuration |
+| **Observability** | Tracing (OpenTelemetry), Logging | Debugging and monitoring |
+| **Build & Packaging** | Cargo (Rust), npm/pnpm (Web) | Dependency and build management |
---
@@ -54,65 +41,78 @@ This modular structure ensures that each component can evolve independently, sup
### System Positioning and Value
-**cortex-mem** is a **full-stack memory management platform** designed specifically for **AI agents**. It enables agents to:
-- Retain context across conversations and tasks
-- Recall relevant past experiences via semantic search
-- Optimize memory quality through deduplication and enhancement
-- Visualize and analyze memory patterns
+`cortex-mem` is a **full-stack memory management system** that provides AI agents with persistent, searchable, and optimizable memory. It enables agents to:
-This capability significantly improves agent **consistency**, **effectiveness**, and **long-term intelligence**, making it a foundational component in advanced AI agent architectures.
+- Retain conversation history and learned knowledge
+- Retrieve relevant memories using semantic search
+- Optimize memory usage by removing duplicates and low-quality entries
+- Integrate seamlessly into agent workflows via multiple protocols
----
+This significantly enhances **agent intelligence, continuity, and user experience** by preventing context loss and enabling long-term learning.
### User Roles and Scenarios
-| Role | Description | Key Use Cases |
-|------|-----------|-------------|
-| **AI Agent Developers** | Engineers integrating memory into AI applications | - Store agent interactions
- Retrieve context before responses
- Monitor memory usage via API |
-| **System Administrators** | Ops teams managing agent infrastructure | - Run memory optimization jobs
- Monitor system health
- Analyze memory trends and costs |
-| **Research Scientists** | Researchers evaluating agent memory systems | - Benchmark recall accuracy
- Test optimization strategies
- Generate synthetic datasets |
-
----
+| Role | Needs | Interaction Scenarios |
+|------|-------|------------------------|
+| **AI Agents** | Store context, retrieve relevant memories, optimize memory usage | Use MCP or API to log interactions and query past experiences |
+| **Developers** | Integrate memory into AI apps, configure behavior, debug | Use CLI, API, or SDKs to build agent systems |
+| **System Administrators** | Monitor health, optimize performance, manage configurations | Use web dashboard and CLI for maintenance and tuning |
### External System Interactions
```mermaid
graph TD
- A[cortex-mem] -->|API Calls| B[LLM Services]
- A -->|gRPC/HTTP| C[Qdrant Vector Database]
- D[AI Agent / App] -->|HTTP Requests| A
- E[Admin User] -->|CLI Commands| A
- F[Researcher] -->|Dashboard Access| A
- G[External Agent Framework] -->|MCP Tool Calls| A
-
- style A fill:#2196F3,stroke:#1976D2,color:white
- style B fill:#FFC107,stroke:#FFA000,color:black
- style C fill:#4CAF50,stroke:#388E3C,color:white
- style D fill:#9E9E9E,stroke:#616161,color:white
- style E fill:#9E9E9E,stroke:#616161,color:white
- style F fill:#9E9E9E,stroke:#616161,color:white
- style G fill:#9E9E9E,stroke:#616161,color:white
-
- classDef user fill:#9E9E9E,stroke:#616161,color:white;
- class D,E,F,G user;
-```
+ subgraph ExternalSystems [External Systems]
+ Qdrant[(Qdrant Vector Database)]
+ OpenAI[(OpenAI LLM Service)]
+ LangMem[(LangMem - Benchmark)]
+ end
-#### Interaction Types:
-- **LLM Services**: Used for embedding generation, classification, keyword extraction, and optimization guidance.
-- **Qdrant**: Primary vector database for storing memory embeddings and metadata.
-- **HTTP Clients**: Access REST API and web dashboard.
-- **CLI Tools**: Direct terminal interaction for scripting and debugging.
-- **MCP Clients**: Integration with agent frameworks using Model Context Protocol.
+ subgraph cortex-mem [cortex-mem System]
+ CLI[cortex-mem-cli]
+ HTTPAPI[cortex-mem-service]
+ MCP[cortex-mem-mcp]
+ WebUI[cortex-mem-insights]
+ Core[cortex-mem-core]
+ end
----
+ CLI --> Core
+ HTTPAPI --> Core
+ MCP --> Core
+ WebUI --> HTTPAPI
+ WebUI --> Core
+
+ Core --> Qdrant
+ Core --> OpenAI
+ HTTPAPI --> OpenAI
+ MCP --> OpenAI
+
+ WebUI -.-> LangMem
+ HTTPAPI -.-> LangMem
+
+ style cortex-mem fill:#2196F3,stroke:#1976D2,color:white
+ style ExternalSystems fill:#9C27B0,stroke:#7B1FA2,color:white
+```
+
+- **Qdrant**: Used for storing and retrieving memory embeddings via vector similarity search.
+- **OpenAI**: Provides text embeddings, content analysis, and structured extraction (facts, entities).
+- **LangMem**: Used for benchmarking and comparative evaluation of memory systems.
### System Boundary Definition
-| Included Components | Excluded Components |
-|---------------------|---------------------|
-| - Memory CRUD operations
- Semantic search with vector embeddings
- Deduplication and optimization
- Analytics dashboard
- REST/CLI/MCP interfaces
- Evaluation framework | - Training of LLMs or embedding models
- Development of vector database engine
- OS-level resource management
- Network infrastructure provisioning |
+#### Included Components
+- Memory storage and retrieval
+- Semantic search capabilities
+- Memory optimization engine
+- Multiple access interfaces (CLI, API, MCP, Web Dashboard)
+- Configuration management
+- Integration with LLM and vector database services
-> 🔒 **Boundary Clarity**: The system **integrates** with external AI and storage services but does **not own** their underlying models or infrastructure.
+#### Excluded Components
+- Core AI agent logic (e.g., reasoning, planning)
+- Application-specific business rules
+- End-user UI design for agent applications
+- Network infrastructure management (e.g., load balancing, firewalls)
---
@@ -120,113 +120,79 @@ graph TD
### Domain Module Division
-The system is structured into **five primary domains**, each representing a logical grouping of functionality:
+The system is divided into six primary domain modules, each responsible for a distinct aspect of functionality:
| Domain | Type | Responsibility |
|-------|------|----------------|
-| **Memory Management Domain** | Core Business | Full lifecycle management of memories (CRUD, retrieval, metadata) |
-| **Memory Storage Domain** | Technical | Persistent storage using vector database (Qdrant) |
-| **Optimization Domain** | Core Business | Improve memory quality via deduplication, relevance tuning, enhancement |
-| **Insights & Analytics Domain** | Support | Visualization, monitoring, and reporting |
-| **Evaluation & Tools Domain** | Support | Benchmarking, testing, and example agents |
-
----
+| **Memory Management Domain** | Core Business | CRUD, classification, search |
+| **Memory Optimization Domain** | Core Business | Deduplication, quality analysis, merging |
+| **LLM Integration Domain** | Core Business | Embedding, extraction, intelligence |
+| **Storage Integration Domain** | Infrastructure | Qdrant interaction, vector persistence |
+| **Access Interface Domain** | Tool Support | CLI, API, MCP, Web UI |
+| **Configuration Management Domain** | Infrastructure | Centralized settings |
### Domain Module Architecture
```mermaid
graph TD
- subgraph "External Systems"
- LLM[LLM Services]
- QDRANT[Qdrant DB]
- HTTP[HTTP Clients]
- CLI[CLI Users]
- MCP[Agent Frameworks]
- end
-
- subgraph "cortex-mem System"
- CORE[cortex-mem-core\n(Memory Engine)]
-
- subgraph Interfaces
- SERVICE[cortex-mem-service\n(Rest API)]
- CLI_INTERFACE[cortex-mem-cli\n(Command Line)]
- MCP_ADAPTER[cortex-mem-mcp\n(MCP Adapter)]
- INSIGHTS[cortex-mem-insights\n(Dashboard UI)]
- end
-
- subgraph Support
- EVAL[cortex-mem-evaluation\n(Benchmarking)]
- TARS[cortex-mem-tars\n(Terminal Agent)]
- end
+ subgraph Domains [Domain Modules]
+ MMD[Memory Management Domain]
+ MOD[Memory Optimization Domain]
+ LLM[LLM Integration Domain]
+ SID[Storage Integration Domain]
+ AID[Access Interface Domain]
+ CMD[Configuration Management Domain]
end
- SERVICE --> CORE
- CLI_INTERFACE --> CORE
- MCP_ADAPTER --> CORE
- INSIGHTS --> SERVICE
- EVAL --> CORE
- TARS --> CORE
-
- CORE --> LLM
- CORE --> QDRANT
-
- HTTP --> SERVICE
- CLI --> CLI_INTERFACE
- MCP --> MCP_ADAPTER
-
- style CORE fill:#4CAF50,stroke:#388E3C,color:white
- style SERVICE fill:#2196F3,stroke:#1976D2,color:white
- style CLI_INTERFACE fill:#9C27B0,stroke:#7B1FA2,color:white
- style MCP_ADAPTER fill:#FF9800,stroke:#F57C00,color:white
- style INSIGHTS fill:#00BCD4,stroke:#00ACC1,color:white
- style EVAL fill:#795548,stroke:#5D4037,color:white
- style TARS fill:#607D8B,stroke:#455A64,color:white
+ AID --> MMD
+ MMD --> LLM
+ MMD --> SID
+ MOD --> MMD
+ LLM --> CMD
+ SID --> CMD
+ MOD --> CMD
+ AID --> CMD
+
+ style MMD fill:#4CAF50,stroke:#388E3C,color:white
+ style MOD fill:#4CAF50,stroke:#388E3C,color:white
+ style LLM fill:#4CAF50,stroke:#388E3C,color:white
+ style SID fill:#2196F3,stroke:#1976D2,color:white
+ style CMD fill:#2196F3,stroke:#1976D2,color:white
+ style AID fill:#607D8B,stroke:#455A64,color:white
```
----
-
### Storage Design
-#### Data Model (Qdrant Collection Schema)
-
-```json
-{
- "id": "uuid",
- "vector": "float[1536]", // Embedding dimension (auto-detected)
- "payload": {
+- **Primary Storage**: Qdrant vector database
+ - Stores memory vectors (embeddings), metadata, and structured content
+ - Supports similarity search via cosine distance
+ - Collections are auto-created based on agent or session context
+- **Metadata Schema**:
+ ```json
+ {
+ "id": "uuid",
"content": "string",
- "metadata": {
- "source": "string",
- "timestamp": "datetime",
- "type": "string",
- "importance": "float",
- "version": "int"
- },
+ "embedding": "float[]",
+ "type": "conversational|factual|procedural",
+ "timestamp": "datetime",
+ "source": "agent|user",
+ "quality_score": "float",
"keywords": ["string"],
- "embedding_model": "string"
+ "entities": ["string"]
}
-}
-```
-
-#### Key Features:
-- **Semantic Search**: Enabled via vector similarity (cosine distance)
-- **Metadata Filtering**: Supports filtering by `type`, `source`, `timestamp`, etc.
-- **Batch Operations**: Efficient bulk insert/update/delete
-- **Auto-detection**: Dynamically detects embedding dimensions from LLM
-
----
+ ```
+- **Indexing Strategy**: HNSW index for fast approximate nearest neighbor search
+- **Persistence**: All writes are synchronous; reads are cached via in-memory LRU where applicable
### Inter-Domain Module Communication
-| From → To | Communication Mechanism | Protocol/Data Format |
-|---------|--------------------------|-----------------------|
-| Memory Management → Storage | Function call (`upsert_point`, `search`) | Rust trait interface (`VectorStore`) |
-| Memory Management → LLM | HTTP API call | JSON over HTTPS |
-| Optimization → Memory Management | Direct method invocation | In-process Rust calls |
-| Insights → Memory Management | REST API call | JSON over HTTP |
-| CLI/API → Core | Shared state (`Arc`) | In-memory Rust objects |
-
-> 🔄 **Communication Pattern**: Most inter-module communication occurs **in-process** via function calls or shared state, ensuring low latency. External access (dashboard, evaluation) uses **REST API** as a secure boundary.
+| From → To | Communication Type | Mechanism |
+|---------|---------------------|----------|
+| Access Interface → Memory Management | Synchronous Request | Function calls (Rust) / HTTP (Web) |
+| Memory Management → LLM Integration | Synchronous API Call | REST to OpenAI |
+| Memory Management → Storage Integration | Synchronous DB Call | gRPC to Qdrant |
+| Memory Optimization → Memory Management | Synchronous Service Call | In-process method invocation |
+| All Domains → Configuration Management | Configuration Pull | TOML file parsing at startup |
---
@@ -234,208 +200,167 @@ graph TD
### Core Functional Components
-#### `cortex-mem-core` – Memory Engine
-
-**Responsibilities**:
-- Orchestrate memory lifecycle
-- Generate embeddings and metadata
-- Execute optimization plans
-- Manage vector store interactions
-
-**Internal Structure**:
-```rust
-pub struct MemoryManager {
- vector_store: Box,
- llm_client: Box,
- fact_extractor: Box,
- memory_updater: Box,
- importance_evaluator: Box,
- duplicate_detector: Box,
- memory_classifier: Box,
-}
-```
-
-**Key Traits**:
-| Trait | Purpose | Implementations |
-|------|--------|----------------|
-| `VectorStore` | Abstracts vector DB operations | `QdrantStore`, `ChromaStore` (planned) |
-| `LLMClient` | Standardizes LLM interactions | `OpenAIClient`, `AnthropicClient`, `LocalLlama` |
-| `DuplicateDetector` | Detects redundant memories | Rule-based, LLM-based, hybrid |
-
----
-
-#### `cortex-mem-service` – REST API
-
-- Built with **Axum**
-- Endpoints:
- - `POST /memories` – Create memory
- - `GET /memories/{id}` – Retrieve by ID
- - `POST /memories/search` – Semantic search
- - `POST /optimization/start` – Trigger optimization
- - `GET /status` – Health check
-- Uses `Arc` for thread-safe access
-- JSON request/response format
-
----
-
-#### `cortex-mem-cli` – Command Line Interface
-
-- Built with **Clap**
-- Commands:
- - `add "content" --type=event`
- - `search "what did I do yesterday?"`
- - `optimize --strategy=dedupe`
- - `list --filter type=belief`
-- Reads config from `config.toml`
-- Asynchronous execution via Tokio
-
----
-
-#### `cortex-mem-mcp` – MCP Protocol Adapter
-
-- Implements **Model Context Protocol (MCP)**
-- Exposes tools:
- - `store_memory(content, metadata)`
- - `query_memories(query, filters)`
- - `list_memories(filter)`
- - `get_memory(id)`
-- Enables integration with agent frameworks like LangChain, AutoGPT
-
----
-
-#### `cortex-mem-insights` – Dashboard UI
-
-- **Frontend**: SvelteKit (TypeScript)
-- **Backend**: Elysia.js (Bun runtime)
-- Features:
- - Memory distribution charts
- - Optimization history timeline
- - Real-time memory stream
- - Search playground
-- Pulls data from `cortex-mem-service` API
-
----
+| Component | Responsibility | Key Functions |
+|---------|----------------|-------------|
+| **MemoryManager** | Central orchestrator | Create, retrieve, update, delete memories; coordinate optimization |
+| **LLMClient** | LLM interaction | Generate embeddings, extract facts, analyze content |
+| **VectorStore (Qdrant)** | Vector persistence | Store/retrieve embeddings, execute similarity search |
+| **OptimizationEngine** | Memory quality control | Detect duplicates, suggest merges, execute cleanup |
+| **MemoryClassifier** | Type inference | Classify memory as conversational, factual, procedural |
+| **MemoryExtractor** | Structured data extraction | Extract keywords, entities, facts using LLM prompts |
### Technical Support Components
-| Component | Purpose | Technology |
-|--------|--------|-----------|
-| `cortex-mem-evaluation` | Benchmark memory recall and effectiveness | Synthetic dataset generation, accuracy scoring |
-| `cortex-mem-tars` | Example terminal agent demonstrating usage | Interactive CLI agent with memory loop |
-
----
+| Component | Responsibility | Key Functions |
+|---------|----------------|-------------|
+| **ConfigManager** | Configuration loading | Parse `config.toml`, validate, provide defaults |
+| **TracingSystem** | Observability | Log spans, metrics, errors via OpenTelemetry |
+| **CLI Interface** | Command-line access | Parse commands, execute workflows, display results |
+| **HTTP API Service** | RESTful access | Handle JSON requests, validate input, return responses |
+| **MCP Server** | Agent protocol interface | Handle MCP tool calls, route to memory functions |
+| **Web Dashboard** | Monitoring UI | Visualize memory stats, trigger optimization, view logs |
### Component Responsibility Division
```mermaid
graph TD
- CLI_INTERFACE -->|Calls| CORE
- SERVICE -->|Exposes| CORE
- MCP_ADAPTER -->|Translates| CORE
- INSIGHTS -->|Fetches| SERVICE
- EVAL -->|Tests| CORE
- TARS -->|Uses| CORE
-
- CORE -->|Uses| LLM_CLIENT[cortex-mem-core::llm::client]
- CORE -->|Uses| VEC_STORE[cortex-mem-core::vector_store::qdrant]
- CORE -->|Uses| MEM_MANAGER[cortex-mem-core::memory::manager]
- CORE -->|Uses| OPTIMIZER[cortex-mem-core::memory::optimizer]
-
- style CORE fill:#4CAF50,stroke:#388E3C,color:white
- style LLM_CLIENT fill:#FFEB3B,stroke:#FDD835,color:black
- style VEC_STORE fill:#FF9800,stroke:#FB8C00,color:black
- style MEM_MANAGER fill:#03A9F4,stroke:#0288D1,color:white
- style OPTIMIZER fill:#8BC34A,stroke:#7CB342,color:white
+ subgraph Components [Component Responsibilities]
+ MM[MemoryManager]
+ LC[LLMClient]
+ VS[VectorStore]
+ OE[OptimizationEngine]
+ MC[MemoryClassifier]
+ ME[MemoryExtractor]
+ CM[ConfigManager]
+ CLI[CLI Interface]
+ API[HTTP API Service]
+ MCP[MCP Server]
+ WD[Web Dashboard]
+ end
+
+ CLI --> MM
+ API --> MM
+ MCP --> MM
+ WD --> API
+ WD --> MM
+
+ MM --> LC
+ MM --> VS
+ MM --> OE
+ MM --> MC
+ MM --> ME
+
+ LC --> OpenAI
+ VS --> Qdrant
+
+ MM --> CM
+ CLI --> CM
+ API --> CM
+ MCP --> CM
+ WD --> CM
+
+ style MM fill:#4CAF50,stroke:#388E3C,color:white
+ style LC fill:#FF9800,stroke:#F57C00,color:white
+ style VS fill:#9C27B0,stroke:#7B1FA2,color:white
+ style OE fill:#FF5722,stroke:#E64A19,color:white
```
+### Component Interaction Relationships
+
+- **Request Flow**:
+ 1. Interface receives request (e.g., `add memory`)
+ 2. ConfigManager provides settings
+ 3. MemoryManager orchestrates:
+ - Classify content
+ - Generate embedding via LLMClient
+ - Extract facts/entities
+ - Store in VectorStore
+ 4. Response returned via interface
+
+- **Optimization Flow**:
+ 1. User triggers optimization
+ 2. OptimizationEngine analyzes memory collection
+ 3. Uses LLMClient to assess similarity
+ 4. Generates plan (merge/delete)
+ 5. Executes via MemoryManager
+ 6. Reports results via Web Dashboard or CLI
+
---
## 5. Key Processes
### Core Functional Processes
-#### Memory Management Process
+#### Memory Creation Process
```mermaid
graph TD
- A[User/Application] --> B{Initiate Memory Operation}
- B --> C[HTTP API / CLI Command]
- C --> D[Process Request]
- D --> E[Generate Embeddings via LLM Client]
- E --> F[Store in Qdrant Vector Database]
- F --> G[Return Success Response with Memory ID]
- G --> A
+ A[User/Agent: Add Memory] --> B[CLI/API/MCP Interface]
+ B --> C[MemoryManager: Classify Type]
+ C --> D[LLMClient: Generate Embedding]
+ D --> E[MemoryExtractor: Extract Facts/Entities]
+ E --> F[MemoryManager: Build Memory Object]
+ F --> G[VectorStore: Persist in Qdrant]
+ G --> H[Return Success]
```
-**Sequence Flow**:
-1. Client sends `POST /memories` with content
-2. Handler calls `MemoryManager::create_memory()`
-3. LLM generates embedding and extracts keywords/classification
-4. Memory stored in Qdrant with full payload
-5. Response returns `201 Created` with memory ID
+#### Memory Retrieval Process
----
+```mermaid
+graph TD
+ A[User/Agent: Search Query] --> B[API/CLI Interface]
+ B --> C[LLMClient: Generate Query Embedding]
+ C --> D[VectorStore: Semantic Search]
+ D --> E[MemoryManager: Apply Metadata Filters]
+ E --> F[Rank & Return Results]
+```
-#### Memory Search Process
+#### Memory Optimization Process
```mermaid
graph TD
- A[User/Application] --> B{Initiate Search}
- B --> C[Send Search Request with Query]
- C --> D[Generate Query Embedding via LLM]
- D --> E[Semantic Search in Qdrant DB]
- E --> F[Apply Metadata Filters]
- F --> G[Return Ranked Matching Memories]
- G --> A
+ A[User: Initiate Optimization] --> B[OptimizationEngine: Analyze Collection]
+ B --> C[LLMClient: Assess Similarity]
+ C --> D[Generate Plan: Merge/Delete]
+ D --> E[Preview & Confirm]
+ E --> F{Execute?}
+ F -->|Yes| G[MemoryManager: Apply Changes]
+ F -->|No| H[Cancel]
+ G --> I[Log Actions]
+ I --> J[Report Results]
```
-**Sequence Flow**:
-1. Client sends `POST /memories/search` with query
-2. Query embedded using same LLM model
-3. Qdrant performs approximate nearest neighbor (ANN) search
-4. Results filtered by metadata (e.g., `type=belief`, `timestamp > 2024`)
-5. Ranked list returned with relevance scores
-
----
+### Technical Processing Workflows
-#### Memory Optimization Process
+#### System Initialization Workflow
```mermaid
-flowchart TD
- Start[Start Optimization] --> Detector[Detect Issues]
- Detector -->|Duplicates| Deduplicator[DeduplicationDetector]
- Detector -->|Low Quality| QualityChecker[QualityAssessment]
- Detector -->|Outdated| TimeAnalyzer[TimeDecayAnalysis]
- Detector -->|Classification| Classifier[ClassificationValidator]
-
- Detector --> Planner[Generate Optimization Plan]
- Planner --> Analyzer[Analyze Impact & Risk]
- Analyzer --> User[Review Recommendations?]
- User -->|Approve| Executor[Execute Actions]
- Executor --> Reporter[Generate Results Report]
- Reporter --> End[Return Summary]
+graph TD
+ A[Load config.toml] --> B[Initialize Tracing]
+ B --> C[Auto-detect LLM Client]
+ C --> D[Auto-detect Vector Store]
+ D --> E[Determine Embedding Dim]
+ E --> F[Create MemoryManager]
+ F --> G[Start CLI]
+ F --> H[Start HTTP API]
+ F --> I[Start MCP Server]
+ F --> J[Start Web Dashboard]
```
-**Key Stages**:
-1. **Detection**: Scan memories for duplicates, low importance, outdated content
-2. **Planning**: Propose merge/delete/enhance actions
-3. **Approval**: Optional human-in-the-loop review
-4. **Execution**: Apply changes via `MemoryUpdater`
-5. **Reporting**: Return summary of actions taken
+### Data Flow Paths
----
+- **Ingress**: Raw text from user/agent → Interface → Core
+- **Processing**: Text → Embedding → Structured data → Metadata enrichment
+- **Egress**: Search results, optimization reports, logs
+- **Storage**: Vector + metadata → Qdrant → Indexed for search
### Exception Handling Mechanisms
-| Failure Type | Handling Strategy |
-|-------------|-------------------|
-| **LLM Timeout** | Retry with exponential backoff (3 attempts) |
-| **Qdrant Unavailable** | Return 503, log error, retry on next operation |
-| **Invalid Request** | Return 400 with validation details |
-| **Duplicate Memory** | Auto-merge or return conflict (configurable) |
-| **Optimization Risk High** | Block execution unless override flag set |
-
-> ⚠️ **Improvement Suggestion**: Add circuit breaker pattern for external dependencies and implement distributed tracing.
+- **LLM Timeout**: Retry with exponential backoff; fallback to cached embeddings if available
+- **Qdrant Unavailable**: Queue operations (in-memory buffer); retry on reconnect
+- **Invalid Configuration**: Fail fast at startup; provide detailed error messages
+- **Memory Corruption**: Validate checksums; isolate and flag corrupted entries
+- **Optimization Safety**: Preview mode required; all destructive actions require confirmation
---
@@ -443,113 +368,75 @@ flowchart TD
### Core Module Implementation
-#### `memory/manager.rs` – Orchestration Hub
+#### MemoryManager (Rust)
+- **Location**: `cortex-mem-core/src/memory/manager.rs`
+- **Key Traits**:
+ ```rust
+ trait MemoryStorage {
+ fn add(&self, memory: Memory) -> Result;
+ fn search(&self, query: &str, filters: Filters) -> Result>;
+ fn update(&self, id: Id, patch: MemoryPatch) -> Result<()>;
+ }
+ ```
-- Single entry point for all memory operations
-- Composes extractors, evaluators, and updaters
-- Thread-safe via `Arc>` or async equivalents
+#### LLMClient (Rust)
+- Uses OpenAI embeddings API (`text-embedding-3-small`)
+- Implements structured extraction via JSON-mode prompting
+- Caches embeddings to reduce API cost
-```rust
-impl MemoryManager {
- pub async fn create_memory(&self, content: String, metadata: Metadata) -> Result {
- let embedding = self.llm_client.embed(&content).await?;
- let keywords = self.llm_client.extract_keywords(&content).await?;
- let memory_type = self.memory_classifier.classify(&content).await?;
- let importance = self.importance_evaluator.score(&content).await?;
-
- let memory = Memory::new(content, embedding, metadata)
- .with_keywords(keywords)
- .with_type(memory_type)
- .with_importance(importance);
-
- self.vector_store.upsert(&memory).await?;
- Ok(memory)
- }
-}
-```
-
----
+#### OptimizationEngine
+- **Duplicate Detection**: Uses cosine similarity + LLM semantic comparison
+- **Quality Scoring**: Based on length, coherence, relevance, and recency
+- **Merge Strategy**: Combines overlapping memories using LLM summarization
### Key Algorithm Design
-#### Hybrid Deduplication Algorithm
-
-```rust
-fn detect_duplicate(&self, new_memory: &Memory, existing: &[Memory]) -> Option {
- // Step 1: Fast rule-based filter (same source + similar timestamp)
- let candidates = rule_filter(new_memory, existing);
-
- // Step 2: Semantic similarity (vector distance < threshold)
- let similar = semantic_filter(new_memory.embedding, &candidates);
-
- // Step 3: LLM validation (are they truly duplicates?)
- if let Some(primary) = similar.first() {
- if self.llm_client.confirm_duplicate(new_memory, primary).await? {
- return Some(primary.id);
- }
- }
- None
-}
+#### Semantic Search Algorithm
+1. Normalize query text
+2. Generate embedding via LLM
+3. Query Qdrant with `with_payload=true`, `with_vectors=false`
+4. Apply metadata filters (date, type, source)
+5. Re-rank using hybrid scoring (similarity + quality score)
+
+#### Optimization Plan Generation
+```python
+def generate_optimization_plan(memories):
+ clusters = cluster_by_similarity(memories, threshold=0.92)
+ plan = []
+ for cluster in clusters:
+ if len(cluster) > 1:
+ primary = select_highest_quality(cluster)
+ for mem in cluster:
+ if mem != primary:
+ plan.append(MergeAction(primary.id, mem.id))
+ return plan
```
-> ✅ **Accuracy**: Combines speed (rules) with precision (LLM)
-
----
-
### Data Structure Design
-#### Memory Object (Rust)
-
```rust
#[derive(Serialize, Deserialize)]
pub struct Memory {
pub id: Uuid,
pub content: String,
pub embedding: Vec,
- pub metadata: HashMap,
+ pub memory_type: MemoryType, // Conversational, Factual, Procedural
+ pub timestamp: DateTime,
+ pub source: String, // Agent ID or User ID
+ pub quality_score: f32,
+ pub facts: Vec,
+ pub entities: Vec,
pub keywords: Vec,
- pub memory_type: MemoryType,
- pub importance: f32,
- pub created_at: DateTime,
- pub updated_at: DateTime,
- pub version: u32,
}
```
-#### Configuration Model (`config.toml`)
-
-```toml
-[server]
-host = "127.0.0.1"
-port = 8080
-
-[qdrant]
-url = "http://localhost:6334"
-collection = "memories"
-
-[llm]
-provider = "openai"
-model = "text-embedding-3-small"
-api_key = "sk-..."
-
-[optimization]
-deduplication_threshold = 0.92
-importance_decay_rate = 0.01
-```
-
----
-
### Performance Optimization Strategies
-| Strategy | Implementation |
-|--------|----------------|
-| **Embedding Caching** | Cache recent embeddings by content hash (planned) |
-| **Batch Processing** | Support bulk insert/search operations |
-| **Async I/O** | All LLM and DB calls are non-blocking |
-| **Indexing** | Qdrant uses HNSW index for fast ANN search |
-| **Connection Pooling** | Reuse HTTP connections to LLM and Qdrant |
-
-> 🚀 **Future Enhancement**: Add Redis cache layer for frequent queries.
+- **Embedding Caching**: Cache embeddings by content hash to avoid redundant LLM calls
+- **Batch Processing**: Support bulk insert/search operations
+- **Index Partitioning**: Split collections by agent or time window
+- **Asynchronous Logging**: Non-blocking trace and metric emission
+- **Connection Pooling**: Reuse HTTP and gRPC connections to Qdrant/OpenAI
---
@@ -557,101 +444,145 @@ importance_decay_rate = 0.01
### Runtime Environment Requirements
-| Component | CPU | Memory | Disk | Network |
-|--------|------|--------|------|---------|
-| `cortex-mem-core` | 2 vCPU | 4 GB | 1 GB (temp) | Outbound to LLM/Qdrant |
-| `cortex-mem-service` | 1 vCPU | 1 GB | - | Inbound HTTP |
-| `cortex-mem-insights` | 1 vCPU | 2 GB | - | Inbound HTTP |
-| Qdrant | 4 vCPU | 8 GB | SSD | Internal gRPC |
-| LLM (external) | N/A | N/A | N/A | Public API |
-
----
+| Component | Language | Runtime | Memory | CPU |
+|--------|---------|--------|-------|-----|
+| Core Engine | Rust | Native binary | 512MB+ | 1 vCPU |
+| HTTP API | Rust | Native binary | 256MB+ | 0.5 vCPU |
+| Web Dashboard | Node.js + Svelte | Node 18+ | 256MB | 0.5 vCPU |
+| Qdrant | Rust | Docker | 2GB+ | 2 vCPU |
+| OpenAI | Cloud | N/A | N/A | N/A |
### Deployment Topology Structure
```mermaid
-graph LR
- subgraph "Cloud / On-Prem"
- LB[Load Balancer]
- subgraph "Application Layer"
- API[cortex-mem-service\nReplica 1-3]
- CLI[CLI Tools]
- end
- subgraph "Core Layer"
- CORE[cortex-mem-core\nShared Engine]
- end
- subgraph "Data Layer"
- QDRANT[Qdrant Cluster]
- CACHE[(Redis Cache)\nOptional]
- end
- subgraph "External"
- LLM[LLM API\n(OpenAI, etc.)]
- BROWSER[Web Browser]
- AGENT[AI Agent]
+graph TD
+ subgraph Cloud [Cloud Environment]
+ subgraph VPC [VPC: cortex-mem-vpc]
+ subgraph Compute [Compute Layer]
+ CLI[CLI - Local or CI]
+ API[cortex-mem-service]
+ MCP[cortex-mem-mcp]
+ WD[cortex-mem-insights]
+ end
+
+ subgraph Data [Data Layer]
+ Qdrant[Qdrant Cluster]
+ PG[PostgreSQL - Optional Metadata]
+ end
+
+ subgraph External [External Services]
+ OpenAI[OpenAI API]
+ LangMem[LangMem Benchmark]
+ end
end
end
- BROWSER --> LB --> API --> CORE
- CLI --> CORE
- AGENT --> API
- CORE --> QDRANT
- CORE --> CACHE
- CORE --> LLM
-
- style CORE fill:#4CAF50,stroke:#388E3C,color:white
- style API fill:#2196F3,stroke:#1976D2,color:white
- style QDRANT fill:#4CAF50,stroke:#388E3C,color:white
- style LLM fill:#FFC107,stroke:#FFA000,color:black
- style CACHE fill:#9C27B0,stroke:#7B1FA2,color:white
+ CLI --> API
+ API --> Qdrant
+ API --> OpenAI
+ MCP --> API
+ WD --> API
+ WD --> Qdrant
+
+ style VPC fill:#E3F2FD,stroke:#2196F3
+ style Compute fill:#BBDEFB,stroke:#1976D2
+ style Data fill:#E1BEE7,stroke:#9C27B0
```
+### Scalability Design
+
+- **Horizontal Scaling**: HTTP API and MCP services can be deployed in multiple instances behind a load balancer
+- **Vertical Scaling**: Qdrant can scale memory and CPU for larger embedding dimensions or collections
+- **Caching Layer**: Optional Redis cache for frequent queries and embeddings
+- **Queue-Based Processing**: Long-running optimization jobs can be offloaded to a message queue (e.g., RabbitMQ)
+
+### Monitoring and Operations
+
+- **Metrics**: Prometheus for latency, request rate, error rate
+- **Tracing**: OpenTelemetry + Jaeger for request flow visibility
+- **Logging**: Structured JSON logs with severity levels
+- **Alerting**: Grafana alerts on high error rates or slow LLM responses
+- **Health Checks**: `/health` endpoint for liveness and readiness
+- **Backup**: Regular snapshots of Qdrant collections
+
---
+## Architecture Insights
+
### Scalability Design
-| Aspect | Strategy |
-|------|----------|
-| **Horizontal Scaling** | Multiple `cortex-mem-service` instances behind load balancer |
-| **Vertical Scaling** | Scale Qdrant and core engine with memory/CPU |
-| **Data Partitioning** | Future support for sharded collections by agent ID |
-| **Streaming Support** | Planned for large search results and long-running optimizations |
+- **Extension Points**:
+ - New interfaces (e.g., WebSocket, gRPC) can be added without modifying core
+ - Additional vector databases (Pinecone, Weaviate) can be integrated via adapter pattern
+ - Custom optimization strategies can be plugged in via trait implementation
----
+- **Future-Proofing**:
+ - Support for multiple LLM providers (Anthropic, Cohere) via abstraction layer
+ - Federated memory across agents using sharding
-### Monitoring and Operations
+### Performance Considerations
+
+- **Bottlenecks**:
+ - LLM API latency (mitigated by caching and batching)
+ - Vector search performance at scale (mitigated by HNSW indexing)
+ - Memory classification overhead (mitigated by lightweight models)
-#### Current Capabilities
-- Health checks (`GET /status`)
-- Logging via `tracing` crate
-- Configuration reload (TOML)
-
-#### Recommended Enhancements
-| Tool | Purpose |
-|------|--------|
-| **Prometheus + Grafana** | Metrics: request rate, latency, memory count |
-| **OpenTelemetry** | Distributed tracing across components |
-| **Sentry** | Error tracking and alerting |
-| **Log Aggregation** | ELK or Loki for centralized logs |
-
-> 🔐 **Security Recommendations**:
-> - Add JWT authentication for API
-> - Rate limiting on public endpoints
-> - Encrypt sensitive config (e.g., API keys)
-> - Role-based access control (RBAC) for dashboard
+- **Optimization Roadmap**:
+ - On-premise embedding models (e.g., BERT, Sentence Transformers)
+ - Incremental optimization (vs. full scans)
+ - In-memory vector cache for hot queries
+
+### Security Design
+
+- **Authentication**: API keys for HTTP/MCP interfaces
+- **Authorization**: Role-based access (read/write/optimization)
+- **Data Encryption**: TLS for all external communications
+- **Secrets Management**: API keys stored in environment variables or secret manager
+- **Input Sanitization**: All user inputs validated and sanitized
---
-## Conclusion
+## Development & Operations Guidance
+
+### Development Guidance
+
+- **Contribution Workflow**:
+ 1. Modify `cortex-mem-core` for business logic
+ 2. Update interfaces as needed
+ 3. Add tests in `tests/` directory
+ 4. Run `cargo test --all-features`
-The **cortex-mem** architecture presents a **robust, modular, and intelligent** solution for AI agent memory management. Its **Rust-based core** ensures performance and safety, while **multiple access interfaces** (REST, CLI, MCP, Dashboard) provide flexibility for diverse users.
+- **Best Practices**:
+ - Keep core logic in `cortex-mem-core`
+ - Use configuration for environment-specific settings
+ - Log all LLM and DB interactions for debugging
-The system effectively combines **vector storage (Qdrant)** with **LLM-powered intelligence** to enable semantic search, automatic metadata enrichment, and proactive optimization. The clear separation of domains and components makes it **easy to extend, maintain, and scale**.
+### Operations Guidance
-### Final Recommendations
-1. **Add Caching Layer** (Redis) to reduce LLM/vector DB load
-2. **Implement Authentication** for production use
-3. **Enhance Observability** with metrics and tracing
-4. **Expand Testing** with unit/integration tests
-5. **Support More Vector Stores** (Chroma, Weaviate) via trait implementation
+- **Deployment**:
+ - Use Docker Compose for local development
+ - Use Kubernetes for production (with HPA and monitoring)
+
+- **Maintenance**:
+ - Schedule nightly optimization jobs
+ - Monitor embedding API usage and costs
+ - Backup Qdrant collections weekly
+
+### Decision Support
+
+- **Why Rust?** Performance, safety, and concurrency for core logic
+- **Why Qdrant?** Open-source, high-performance vector DB with rich filtering
+- **Why Multiple Interfaces?** Supports diverse integration scenarios
+- **Why Centralized Core?** Ensures consistency and reduces duplication
+
+### Knowledge Transfer
+
+New team members should:
+1. Read `config.toml` to understand system settings
+2. Study `cortex-mem-core/src/memory/manager.rs` for core logic
+3. Run CLI commands to see end-to-end flow
+4. Explore web dashboard for monitoring capabilities
+
+---
-This architecture is well-positioned to serve as a **foundational memory layer** in next-generation AI agent systems.
\ No newline at end of file
+**End of Document**
\ No newline at end of file
diff --git a/litho.docs/3.Workflow.md b/litho.docs/3.Workflow.md
index c0337c1..5ddaa69 100644
--- a/litho.docs/3.Workflow.md
+++ b/litho.docs/3.Workflow.md
@@ -1,226 +1,189 @@
# Core Workflows
-**Document Generated On:** 2025-12-18 11:29:14 UTC
-**System Name:** `cortex-mem` – A Comprehensive Memory Management System for AI Agents
-
----
-
## 1. Workflow Overview
-The **cortex-mem** system is a full-stack memory management platform designed to enable AI agents with persistent, searchable, and optimizable long-term memory. It supports multiple interaction modes—via HTTP API, CLI, MCP protocol, and interactive TUI applications—and provides advanced capabilities such as semantic search, deduplication, quality optimization, and analytics.
+The **Cortex-Mem** system is a comprehensive memory management platform designed to enable AI agents and human operators to store, retrieve, analyze, and optimize persistent memories across multiple interaction modalities. The system supports diverse access patterns through CLI, HTTP API, MCP (Memory Control Protocol), and a web-based dashboard, all unified under a shared core logic layer.
-### Main Workflows
-The system revolves around three core workflows:
-1. **Memory Management Process (CRUD)** – Creation, retrieval, update, and deletion of memories.
-2. **Memory Search Process** – Semantic and metadata-based querying of stored memories.
-3. **Memory Optimization Process** – Quality improvement through deduplication, relevance tuning, and structural refinement.
-
-These workflows are orchestrated across modular domains including **Memory Management**, **Memory Storage**, **Optimization**, and **Insights & Analytics**, all coordinated via shared state, configuration, and asynchronous execution.
+### System Main Workflows
+- **Memory Management Workflow**: End-to-end lifecycle of creating, storing, retrieving, and optimizing memories.
+- **System Initialization Workflow**: Bootstrapping process that loads configuration, initializes services, and exposes interfaces.
+- **Optimization Execution Workflow**: Intelligent analysis and improvement of memory collections for quality, relevance, and efficiency.
### Core Execution Paths
-| Workflow | Entry Point(s) | Key Output |
-|--------|----------------|-----------|
-| Memory Management | `/memories` (API), `add`, `delete` (CLI) | Memory ID or operation status |
-| Memory Search | `/search`, `list`, `search` commands | Ranked list of matching memories |
-| Memory Optimization | `/optimization/start`, `optimize` command | Optimization report with impact metrics |
+1. **User-initiated Memory Operations** (via CLI or Web UI)
+2. **Agent-initiated Memory Access** (via MCP or API)
+3. **Automated Optimization & Maintenance**
+4. **Monitoring & Diagnostic Queries**
### Key Process Nodes
-- **Request Initiation**: User or agent triggers an action via CLI, API, or UI.
-- **Embedding Generation**: LLM client generates vector embeddings from text content.
-- **Vector Storage/Retrieval**: Qdrant database stores and retrieves embeddings using approximate nearest neighbor (ANN) search.
-- **Filtering & Scoring**: Metadata filters applied post-semantic search; results ranked by relevance score.
-- **Optimization Orchestration**: Detection of duplicates, low-quality entries, and relevance issues followed by LLM-driven cleanup.
-- **Response Delivery**: Structured response returned to client with success/failure status and data.
+| Node | Description |
+|------|-------------|
+| `Configuration Load` | Parses TOML config with fallback paths; sets up logging, LLM, vector DB, and service parameters |
+| `MemoryManager Init` | Central orchestrator that binds storage, LLM, and optimization logic |
+| `Content Analysis` | Uses LLM to extract facts, entities, keywords, and classify memory type |
+| `Embedding Generation` | Converts text into vector representations using OpenAI or compatible models |
+| `Vector Storage` | Persists embeddings in Qdrant with metadata indexing |
+| `Semantic Search` | Matches queries via cosine similarity on vectors |
+| `Optimization Engine` | Detects duplicates, low-quality entries, and suggests merging strategies |
+| `State Reporting` | Aggregates health metrics from backend services for monitoring |
### Process Coordination Mechanisms
-- **Asynchronous Communication**: All operations use async/await patterns via Tokio runtime for non-blocking I/O.
-- **Shared State via Arc/Mutex**: In CLI and TUI apps, `Arc` enables thread-safe access.
-- **Configuration-Driven Initialization**: TOML-based config (`config.toml`) controls subsystem behavior (LLM, Qdrant, logging).
-- **Event Loop Architecture**: Interactive tools like `cortex-mem-tars` use message-passing loops for input handling and rendering.
-
-```mermaid
-graph TD
- subgraph "User Interfaces"
- A[HTTP Client] --> C[cortex-mem-service]
- B[Terminal User] --> D[cortex-mem-cli]
- E[AI Agent] --> F[cortex-mem-mcp]
- G[TUI Application] --> H[cortex-mem-tars]
- end
-
- C --> I[cortex-mem-core]
- D --> I
- F --> I
- H --> I
-
- subgraph "Core Engine"
- I --> J[LLM Client]
- I --> K[Qdrant Vector Store]
- end
-
- I --> L[cortex-mem-insights]
- L --> M[Dashboard UI]
-
- style I fill:#4a90e2,color:white
- style J fill:#50c878,color:white
- style K fill:#d64161,color:white
-```
-
-> **Figure 1: High-Level System Architecture and Workflow Coordination**
+- **Shared State via `Arc`**: Ensures thread-safe access across async handlers in Rust components.
+- **Event-Driven Communication**: Message passing between UI and background tasks using channels (`mpsc::UnboundedSender`) in TUI applications.
+- **API Abstraction Layer**: TypeScript client encapsulates REST interactions, enabling consistent frontend-backend communication.
+- **Reactive Stores (Svelte)**: Frontend state managed via writable/derived stores for real-time updates.
+- **Tracing Integration**: Unified logging across modules using `tracing` crate for observability.
---
## 2. Main Workflows
-### 2.1 Memory Management Process
+### 2.1 Memory Management Workflow
-This is the foundational CRUD workflow enabling creation, reading, updating, and deletion of memory records.
+This is the primary business workflow, governing how memories are created, stored, retrieved, and optimized.
-#### Execution Path
```mermaid
-sequenceDiagram
- participant U as User/Application
- participant CLI as cortex-mem-cli
- participant API as cortex-mem-service
- participant MM as MemoryManager
- participant LLM as LLM Client
- participant VS as Qdrant Vector Store
-
- U->>CLI: add --content "Hello world"
- CLI->>MM: create_memory(content)
- MM->>LLM: generate_embedding(content)
- LLM-->>MM: embedding vector
- MM->>VS: upsert(memory + embedding)
- VS-->>MM: success
- MM-->>CLI: memory_id
- CLI-->>U: Created memory ID: abc123
+graph TD
+ A[User/Agent Request] --> B{Operation Type}
+ B -->|Create| C[Content Analysis & Classification]
+ B -->|Search| D[Generate Query Embedding]
+ B -->|Optimize| E[Analyze Memory Collection]
+
+ C --> F[Extract Facts, Entities, Keywords]
+ F --> G[Generate Memory Embedding]
+ G --> H[Store in Qdrant DB]
+
+ D --> I[Vector Similarity Search]
+ I --> J[Apply Metadata Filters]
+ J --> K[Return Ranked Results]
+
+ E --> L[Detect Duplicates & Issues]
+ L --> M[Generate Optimization Plan]
+ M --> N[Execute Merge/Delete Operations]
+
+ H --> P((Persistent Storage))
+ K --> Q[Display Results]
+ N --> R[Update Memory State]
+
+ style A fill:#4CAF50,stroke:#388E3C
+ style Q fill:#2196F3,stroke:#1976D2
+ style P fill:#FF9800,stroke:#F57C00
```
-#### Detailed Steps
-| Step | Component | Operation | Input | Output |
-|------|---------|----------|-------|--------|
-| 1 | `cortex-mem-cli/src/main.rs` | Parse CLI args, dispatch to `add` command | Command-line arguments | `AddCommand` struct |
-| 2 | `cortex-mem-cli/src/commands/add.rs` | Extract content, detect conversation format | Raw string input | Parsed `MemoryContent` |
-| 3 | `cortex-mem-core/src/memory/manager.rs` | Call `create_memory()` | Content, user/agent IDs | Memory object |
-| 4 | `cortex-mem-core/src/llm/client.rs` | Generate embedding via LLM API | Text content | `[f32; 384]` vector |
-| 5 | `cortex-mem-core/src/vector_store/qdrant.rs` | Upsert into Qdrant collection | Memory + embedding | Success/Failure |
-| 6 | `cortex-mem-cli/src/commands/add.rs` | Print result to console | Memory ID | Human-readable output |
-
-#### Business Value
-- Enables AI agents to persist context across sessions.
-- Supports structured metadata tagging (topics, keywords, type).
-- Provides reliable storage with unique identifiers for future reference.
-
-#### Technical Characteristics
-- **Idempotent Operations**: Duplicate inserts return existing ID if detected.
-- **Batch Support**: Bulk operations supported via `/batch` endpoints.
-- **Async I/O**: All steps executed asynchronously using Tokio.
+#### Execution Order and Dependencies
+1. **Input Reception** → Command parsing (CLI) or route dispatch (HTTP/MCP)
+2. **Preprocessing** → Content classification, role detection (e.g., "User:", "Assistant:")
+3. **LLM Interaction** → Fact extraction, embedding generation
+4. **Storage Operation** → Vector write to Qdrant + metadata persistence
+5. **Indexing & Retrieval** → Semantic search using vector similarity
+6. **Post-processing** → Filtering by user_id, agent_id, topics, etc.
+7. **Output Formatting** → Structured console output or JSON response
+
+#### Input/Output Data Flows
+| Step | Input | Output | Source Module | Target Module |
+|------|-------|--------|---------------|----------------|
+| Create | Raw text/conversation | Classified content | CLI/API | Memory Types System |
+| Extract | Text content | Facts, entities, keywords | Information Extraction | Memory CRUD |
+| Embed | Text | Vector embedding | LLM Client | Vector Store |
+| Store | Memory object | Stored ID | Memory Manager | Qdrant |
+| Search | Query string/filters | List of scored memories | Semantic Search | Access Interface |
+| Optimize | Strategy + filters | Optimization plan | Optimization Engine | Memory Manager |
+
+> ✅ **Business Value**: Enables contextual continuity in AI agents by preserving conversational history and derived insights.
---
-### 2.2 Memory Search Process
+### 2.2 System Initialization Workflow
-Enables users and agents to retrieve relevant memories based on semantic similarity or metadata filtering.
+Handles bootstrapping of the entire system across all entry points.
-#### Execution Path
```mermaid
graph TD
- A[User/App] --> B{Initiate Search}
- B --> C[Send Query + Filters]
- C --> D[Generate Embedding via LLM]
- D --> E[Semantic Search in Qdrant]
- E --> F[Apply Metadata Filters]
- F --> G[Rank & Return Results]
- G --> A
+ A[Load Configuration] --> B[Initialize Tracing & Logging]
+ B --> C{Auto-detect Components}
+ C --> D[Detect Vector Store]
+ C --> E[Detect LLM Client]
+ C --> F[Determine Embedding Dimension]
+
+ D --> G[Create MemoryManager]
+ E --> G
+ F --> G
+
+ G --> H[Expose Interfaces]
+ H --> I[CLI Interface]
+ H --> J[HTTP API Service]
+ H --> K[MCP Server]
+ H --> L[Web Dashboard]
+
+ style A fill:#4CAF50,stroke:#388E3C
+ style I fill:#2196F3,stroke:#1976D2
+ style J fill:#2196F3,stroke:#1976D2
+ style K fill:#2196F3,stroke:#1976D2
+ style L fill:#2196F3,stroke:#1976D2
```
-#### Detailed Steps
-| Step | Module | Function | Description |
-|------|--------|--------|-------------|
-| 1 | `handlers.rs::search_memories` | Receive `/search` request | Accepts query string and optional filters (user_id, agent_id, topics) |
-| 2 | `llm/client.rs::generate_embedding` | Encode query into vector | Uses configured LLM (e.g., OpenAI, Ollama) to embed query |
-| 3 | `qdrant.rs::semantic_search` | Perform ANN search | Retrieve top-K nearest neighbors above threshold |
-| 4 | `memory/manager.rs::apply_filters` | Filter by metadata | Apply user, agent, topic, keyword constraints |
-| 5 | `memory/manager.rs::rank_results` | Re-rank by composite score | Combine semantic score with importance, recency, relevance |
-| 6 | `handlers.rs` | Return JSON response | Paginated list with scores, metadata, and snippets |
-
-#### Supported Query Modes
-- **Semantic Only**: Free-text search ("What did I say about planning?")
-- **Metadata Filtered**: List all memories for a given agent/topic
-- **Hybrid**: "Find conversations about goals" → semantic + filter on `type=conversation`
-
-#### Performance Notes
-- Default limit: 20 results
-- Configurable scoring weights: `relevance_weight`, `importance_weight`, `recency_decay`
-- Caching layer planned but not yet implemented
+#### Technical Details
+- **Config Loading Path Resolution**:
+ - Current directory → Home directory → System-wide locations
+ - Supports default values via `Default` trait (e.g., log level = INFO)
+- **Auto-Detection Logic**:
+ - If embedding dimension not specified, infers from LLM model or tests dynamically
+ - Falls back to common dimensions (e.g., 1536 for OpenAI)
+- **Service Binding**:
+ - All interfaces share the same `MemoryManager` instance wrapped in `Arc>`
+ - Tokio runtime manages concurrent access
+
+> ⚙️ **Operational Insight**: This modular initialization enables deployment flexibility—developers can run only needed interfaces (e.g., just MCP server).
---
-### 2.3 Memory Optimization Process
+### 2.3 Optimization Execution Workflow
-A high-value workflow that improves memory quality by detecting and resolving issues such as duplication, redundancy, and poor structure.
+Enables intelligent cleanup and enhancement of memory collections.
-#### Execution Path
```mermaid
-sequenceDiagram
- participant U as User
- participant O as Optimizer CLI
- participant OD as OptimizationDetector
- participant OP as OptimizerEngine
- participant MM as MemoryManager
- participant LLM as LLM Service
-
- U->>O: optimize --strategy deduplicate --preview
- O->>OD: detect_issues(filters)
- OD->>MM: list_all_memories()
- MM-->>OD: memory batch
- OD->>LLM: analyze_for_duplicates(batch)
- LLM-->>OD: issue report
- OD-->>O: preview plan
- U->>O: confirm execution
- O->>OP: execute_plan(plan)
- OP->>LLM: rewrite/refactor memories
- OP->>MM: update/delete affected memories
- OP-->>O: optimization_report
- O-->>U: Display summary and impact
+graph TD
+ A[User Initiates Optimization] --> B[Select Strategy & Filters]
+ B --> C[Analyze Memory Collection]
+ C --> D[Identify Duplicates & Issues]
+ D --> E[Use LLM for Similarity Assessment]
+ E --> F[Generate Optimization Plan]
+ F --> G[Preview Changes & Confirm]
+ G --> H{Execute?}
+ H -->|Yes| I[Apply Changes via MemoryManager]
+ H -->|No| J[Cancel]
+
+ I --> K[Merge Related Memories]
+ I --> L[Delete Redundant Entries]
+ I --> M[Update Memory Metadata]
+
+ K --> N[Log Actions & Metrics]
+ L --> N
+ M --> N
+
+ N --> O[Report Results & Statistics]
+ O --> P[Display Optimization Summary]
+
+ style A fill:#4CAF50,stroke:#388E3C
+ style P fill:#2196F3,stroke:#1976D2
```
-#### Key Subprocesses
-1. **Issue Detection**
- - Scan memories for:
- - Exact or near-duplicate content
- - Low-importance scores (< 0.3)
- - Poorly structured entries
- - Redundant information across related memories
- - Implemented in `optimization_detector.rs`
-
-2. **Plan Generation**
- - Build safe transformation plan:
- - Merge duplicates
- - Rewrite unclear entries
- - Archive obsolete memories
- - Preview mode shows proposed changes before execution
-
-3. **Execution Engine**
- - Apply transformations using LLM rewriting prompts
- - Batch updates to minimize API calls
- - Track version history for rollback capability
-
-4. **Reporting**
- - Generate JSON and Markdown reports
- - Include statistics: # resolved, # deleted, # updated, estimated quality gain
-
-#### Configuration Options
-| Parameter | Default | Purpose |
-|---------|--------|--------|
-| `--strategy` | `full` | One of: `deduplicate`, `quality`, `relevance`, `full` |
-| `--filter-user` | all | Restrict scope to specific user |
-| `--dry-run` | false | Show what would be done without applying changes |
-| `--aggressive` | false | Enable deeper restructuring (riskier) |
-
-#### Business Value
-- Prevents memory bloat and degradation over time.
-- Maintains high signal-to-noise ratio in agent knowledge base.
-- Enables trustworthiness of retrieved context.
+#### Supported Strategies
+| Strategy | Purpose |
+|--------|---------|
+| Full | Comprehensive scan and optimization |
+| Incremental | Only recent memories |
+| Deduplication | Find and merge near-duplicate entries |
+| Quality | Remove low-importance or irrelevant memories |
+| Relevance | Filter based on topic alignment |
+| Space | Maximize storage efficiency |
+
+#### Preview Mode Safety
+- Shows estimated impact before execution
+- Requires explicit confirmation
+- Supports dry-run analysis without modification
+
+> 🔐 **Security Note**: Interactive confirmation prevents accidental data loss during bulk operations.
---
@@ -228,107 +191,82 @@ sequenceDiagram
### 3.1 Multi-Module Coordination Mechanisms
-The system uses a layered architecture where higher-level interfaces delegate to a unified core engine.
+| Relationship | Mechanism | Example |
+|------------|-----------|--------|
+| **Access Interface → Memory Management** | Direct function call via `MemoryManager` | CLI calls `.add_memory()` |
+| **Memory Management → LLM Integration** | Async method invocation | `llm_client.generate_embedding()` |
+| **Memory Management → Storage Integration** | Vector store abstraction | `QdrantStore.store_embedding()` |
+| **Frontend → Backend** | RESTful API over HTTP | `/api/memory/search` |
+| **Agent → System** | MCP protocol over stdio | `store_memory`, `query_memory` tools |
-#### Inter-Module Dependencies
+#### Inter-Process Communication Diagram
```mermaid
-graph LR
- CLI[cortex-mem-cli] --> CORE[cortex-mem-core]
- API[cortex-mem-service] --> CORE
- MCP[cortex-mem-mcp] --> CORE
- EVAL[cortex-mem-evaluation] --> CORE
- INSIGHTS[cortex-mem-insights] --> API
- CORE --> LLM[LLM Client]
- CORE --> VEC[Qdrant]
-
- classDef domain fill:#e0f7fa,stroke:#0097a7;
- class CLI,API,MCP,EVAL,INSIGHTS domain;
-```
-
-> **Figure 2: Module Interaction Diagram**
-
-Each interface module acts as a facade:
-- **CLI**: Terminal-first UX with rich formatting and interactivity
-- **API**: RESTful interface for integration with external systems
-- **MCP**: Protocol adapter for AI tool calling (e.g., LangChain, AutoGPT)
-- **Insights**: Visualization dashboard built on top of API
+sequenceDiagram
+ participant User
+ participant CLI as cortex-mem-cli
+ participant API as cortex-mem-service
+ participant MCP as cortex-mem-mcp
+ participant MM as MemoryManager
+ participant LLM as LLM Client
+ participant VS as Qdrant Vector Store
-All route through `MemoryManager`, ensuring consistent business logic enforcement.
+ User->>CLI: add --content "Hello"
+ CLI->>MM: add_memory(content)
+ MM->>LLM: generate_embedding(text)
+ LLM-->>MM: embedding vector
+ MM->>VS: insert(embedding, metadata)
+ VS-->>MM: success
+ MM-->>CLI: memory ID
+ CLI-->>User: "Memory added: id=abc123"
+
+ User->>API: POST /api/memory/search {query:"greeting"}
+ API->>MM: search(query)
+ MM->>LLM: generate_embedding(query)
+ MM->>VS: query_by_vector(embedding)
+ VS-->>MM: list of IDs
+ MM->>VS: get_metadata_batch(IDs)
+ MM-->>API: ranked results
+ API-->>User: JSON response
+```
### 3.2 State Management and Synchronization
-#### Shared State Patterns
-| Context | Mechanism | Example |
-|-------|----------|--------|
-| CLI App | `Arc` | Thread-safe sharing between event loop and background tasks |
-| TUI App | Message Passing (`mpsc::UnboundedSender`) | Decouple UI rendering from memory persistence |
-| Web Server | `AppState` with `Arc>` | Share manager across Axum handlers |
-| Frontend | Svelte Stores (`writable`, `derived`) | Reactive state for dashboards |
-
-#### Lifecycle Coordination
-In `cortex-mem-tars`, graceful shutdown ensures:
-1. Exit TUI immediately on `/quit`
-2. Continue processing pending memory saves in background
-3. Log final session summary after persistence completes
-
-Implemented via Tokio task spawning and join handles.
+#### Backend (Rust)
+- **Thread Safety**: Shared state protected via `Arc>` or `Arc>`
+- **Async Runtime**: Tokio handles concurrency with non-blocking I/O
+- **Global Config**: Immutable after load, cloned where needed
+
+#### Frontend (Svelte)
+- **Reactive Stores**:
+ - `memoryStore`: Holds list of memories with filters
+ - `optimizationStore`: Tracks job status and history
+ - `systemStore`: Monitors backend health
+- **Derived Stores**:
+ ```ts
+ export const optimizationStatus = derived(
+ optimizationStore,
+ ($store) => $store.job?.status || 'idle'
+ );
+ ```
### 3.3 Data Passing and Sharing
-#### Internal Data Flow
-```mermaid
-flowchart LR
- Input --> Normalization --> Embedding --> Storage --> Indexing --> Queryable
-```
-
-Data transformations include:
-- UTF-8 normalization and truncation (max 16k tokens)
-- Automatic topic extraction from content
-- Importance scoring via LLM classification
-- Vector indexing within Qdrant
-
-#### Cross-Layer Contracts
-Defined via:
-- Rust structs (`MemoryRecord`, `Filters`, `OptimizationPlan`)
-- TypeScript interfaces (`ApiMemory`, `OptimizationJobStatus`)
-- Serde serialization for inter-process communication
-
-Ensures consistency between CLI, API, and frontend layers.
+| Layer | Mechanism | Format |
+|------|----------|--------|
+| Internal (Rust) | Function arguments, structs | Native types (`Memory`, `Filters`) |
+| External (API) | JSON over HTTP | Defined in `types.ts` |
+| CLI ↔ Core | In-process calls | Strongly-typed Rust structs |
+| Agent ↔ MCP | JSON-RPC over stdio | MCP-compliant tool schema |
### 3.4 Execution Control and Scheduling
-#### Asynchronous Processing Model
-All heavy operations run asynchronously:
-- Embedding generation
-- Vector search
-- Optimization jobs
-- Batch imports
-
-Using **Tokio** runtime with:
-- Task spawning for long-running operations
-- Timeouts enforced per operation (configurable)
-- Backpressure via bounded channels
-
-#### Job Tracking
-Optimization jobs tracked in-memory (future: persistent store):
-- Job ID generation
-- Status polling endpoint (`GET /optimization/status/:id`)
-- Cancellation support via cancellation tokens
-
-Example job lifecycle:
-```mermaid
-stateDiagram-v2
- [*] --> Idle
- Idle --> Analyzing: start_optimization()
- Analyzing --> Executing: issues_detected
- Executing --> Completed: all_applied
- Executing --> Failed: error_during_apply
- Analyzing --> Cancelled: cancel_request
- Executing --> Cancelled: cancel_request
- Failed --> [*]
- Completed --> [*]
- Cancelled --> [*]
-```
+- **Manual Triggering**: User commands via CLI or Web UI
+- **Scheduled Jobs**: Planned via external schedulers (not built-in yet)
+- **Concurrent Processing**:
+ - Multiple CLI/API requests handled concurrently via Tokio
+ - Batch operations use rate limiting (1s delay between batches)
+
+> 🔄 **Performance Tip**: Use batch operations for large-scale imports to reduce overhead.
---
@@ -336,66 +274,54 @@ stateDiagram-v2
### 4.1 Error Detection and Handling
-#### Common Failure Points
-| Layer | Potential Errors | Handling Strategy |
-|------|------------------|-------------------|
-| CLI Parsing | Invalid args | Clap validation + help display |
-| LLM Call | Rate limiting, timeout, auth failure | Retry with exponential backoff; fallback to cached embedding if available |
-| Qdrant DB | Connection loss, index corruption | Graceful degradation; log warning, retry on next attempt |
-| Memory Write | Duplicate key, schema mismatch | Idempotent insert; deduplicate before write |
-| Optimization | Invalid plan, partial failure | Atomic transaction simulation; roll back failed batches |
-
-#### Centralized Logging
-Uses `tracing_subscriber` with structured logs:
-```rust
-tracing::error!(error = ?e, memory_id, "Failed to delete memory");
-```
-Log levels: INFO (default), DEBUG (verbose), ERROR (critical)
+| Component | Strategy |
+|---------|----------|
+| **CLI** | Structured tracing logs + user-friendly messages |
+| **HTTP API** | Centralized error handler returns `{success: false, error: {...}}` |
+| **MCP Server** | Translates domain errors to `ErrorData` per MCP spec |
+| **Frontend** | Try-catch blocks with fallback rendering |
+
+#### Common Errors and Responses
+| Error Type | Handling |
+|----------|---------|
+| `Memory Not Found` | Return 404; suggest alternatives if similar exist |
+| `LLM Rate Limit` | Retry with exponential backoff; fall back to cached embeddings |
+| `Qdrant Unavailable` | Log error; return cached results if possible |
+| `Invalid Configuration` | Fail fast at startup with descriptive message |
+| `JSON Parse Failure` | Graceful degradation; use defaults or skip item |
### 4.2 Exception Recovery Mechanisms
-#### Resilience Features
-- **Retry Logic**: For transient failures (network, rate limits)
-- **Fallback Embeddings**: Use last-known-good embedding during outages
-- **Safe Mode**: Disable optimization when LLM unavailable
-- **Data Validation**: Validate memory integrity before and after operations
-
-#### Rollback Capabilities
-- Memory updates preserve previous versions (soft-delete model)
-- Optimization plans can be reverted using audit trail
-- Backup export via `cortex-mem-cli list --format=json > backup.json`
+- **Graceful Degradation**:
+ - When LLM fails, use basic keyword matching instead of semantic search
+ - On API failure, show last known good state
+- **Retry Logic**:
+ - Python evaluation scripts include retry loops
+ - HTTP clients implement automatic retries (configurable)
+- **Fallback Modes**:
+ - CLI optimization has “preview” mode to avoid unintended changes
+ - Web UI shows mock data when backend is unreachable
### 4.3 Fault Tolerance Strategy Design
-| Risk | Mitigation |
+| Aspect | Strategy |
|------|----------|
-| Single Point of Failure | Stateless services; Qdrant supports clustering |
-| Data Loss | Regular backups encouraged; WAL enabled in Qdrant |
-| LLM Outage | Cache recent embeddings; degrade to keyword-only search |
-| High Load | Request throttling; queue large jobs |
-| Misconfiguration | Schema validation on config load; defaults provided |
+| **Data Loss Prevention** | Final shutdown phase ensures pending writes complete |
+| **Service Isolation** | Each interface runs independently; one crash doesn’t affect others |
+| **Idempotent Operations** | Add operations check for duplicates before insertion |
+| **Backup Support** | Optimization includes optional backup creation before major changes |
### 4.4 Failure Retry and Degradation
-#### Retry Policy
-Configurable in `config.toml`:
-```toml
-[llm.retry]
-max_attempts = 3
-initial_backoff_ms = 500
-max_backoff_ms = 5000
-jitter_factor = 0.1
-```
-
-Applied automatically in `client.rs`.
-
-#### Degradation Modes
-When LLM service is unreachable:
-- **Search**: Fall back to metadata-only filtering
-- **Add**: Skip embedding, mark as "pending embedding"
-- **Optimize**: Disable LLM-dependent strategies, allow manual cleanup only
+- **Rate Limit Handling**:
+ - Detected via HTTP 429 or LLM client feedback
+ - Automatically switches to lower-frequency mode
+ - Delays next request using jittered exponential backoff
+- **Degraded Mode Features**:
+ - Disable advanced features (e.g., deduplication) when LLM unavailable
+ - Fall back to exact match search when embedding generation fails
-Indicated in system status dashboard.
+> 💡 **Best Practice**: Always validate configuration early using `validate_config()` utilities to prevent runtime failures.
---
@@ -403,133 +329,128 @@ Indicated in system status dashboard.
### 5.1 Core Algorithm Processes
-#### Embedding Pipeline
+#### Memory Creation Pipeline
```rust
-async fn create_memory(&self, content: String) -> Result {
- let embedding = self.llm_client.generate_embedding(&content).await?;
- let memory = MemoryRecord::new(content, embedding, self.user_id);
- self.vector_store.upsert(memory).await?;
- Ok(memory.id)
+async fn create_memory(content: &str) -> Result {
+ let memory_type = classify_content(content);
+ let facts = extractor.extract_facts(content).await?;
+ let embedding = llm_client.embed(content).await?;
+ let metadata = MemoryMetadata::new(user_id, agent_id, memory_type);
+
+ let memory = Memory::builder()
+ .content(content)
+ .embedding(embedding)
+ .metadata(metadata)
+ .facts(facts)
+ .build();
+
+ memory_manager.store(memory).await
}
```
-- Uses sentence-transformers or OpenAI models
-- Dimension: typically 384–1536 floats
-- Distance metric: Cosine similarity
-
-#### Deduplication Algorithm
-1. Group memories by user + agent
-2. Compute pairwise cosine distances
-3. Cluster similar vectors (threshold: 0.92)
-4. Select representative memory (highest importance + recency)
-5. Rewrite others to link or merge
-Uses hierarchical agglomerative clustering (HAC).
-
-#### Importance Scoring
-Uses few-shot prompting:
+#### Optimization Decision Hierarchy
```text
-Rate this memory's importance from 0.0 to 1.0:
-- Is it actionable?
-- Does it contain personal facts?
-- Will it be useful later?
-
-Content: "{content}"
-→ Score:
+Preference Order:
+IGNORE > MERGE > UPDATE > CREATE
+
+Rules:
+1. If new fact matches existing closely → IGNORE
+2. If related but complementary → MERGE (summarize)
+3. If outdated/incomplete → UPDATE
+4. Otherwise → CREATE new memory
```
-Score normalized and combined with length, source, and frequency.
### 5.2 Data Processing Pipelines
-#### Ingestion Pipeline
+#### Ingestion Flow
```mermaid
flowchart LR
- RawInput --> Parser --> Cleaner --> Classifier --> Embedder --> Indexer --> Stored
+ RawInput --> Parser{是否为对话}
+ Parser -->|"是"| RoleSplit[拆分为用户和助手]
+ Parser -->|"否"| DirectStore
+ RoleSplit --> BatchProcessor
+ BatchProcessor --> Embedder
+ Embedder --> Extractor
+ Extractor --> Classifier
+ Classifier --> Storage
```
-Steps:
-1. **Parse**: Detect conversation turns (`User:` / `Assistant:`)
-2. **Clean**: Remove noise, normalize whitespace
-3. **Classify**: Assign `type` (fact, conversation, goal, etc.)
-4. **Extract Topics**: Keyword extraction via TF-IDF + LLM suggestion
-5. **Generate Embedding**
-6. **Index**: Insert into Qdrant with payload (metadata)
-
-#### Search Pipeline
+#### Search Flow
```mermaid
flowchart LR
- Query --> Embed --> ANN --> Filter --> Rerank --> Format --> Return
+ Query --> EmbedQuery
+ EmbedQuery --> VectorSearch["Find top-k similar vectors"]
+ VectorSearch --> FetchMetadata
+ FetchMetadata --> ApplyFilters["Filter by user_id, agent_id, topics"]
+ ApplyFilters --> RankResults["Score by relevance + recency"]
+ RankResults --> FormatOutput
```
-Post-processing includes:
-- Snippet generation (context window around match)
-- Highlighting query terms
-- Recency boost: `score *= exp(-λ * age_in_days)`
-
### 5.3 Business Rule Execution
-#### Memory Retention Policies
-| Type | Default TTL | Configurable |
-|------|------------|-------------|
-| Conversation | 90 days | Yes |
-| Fact | Permanent | Yes |
-| Temporary Note | 7 days | Yes |
-| Goal | Until completion | Auto-archive |
+| Rule | Enforcement Point |
+|------|-------------------|
+| No duplicate memories within 5 minutes | At ingestion time via timestamp + hash check |
+| Maximum 100 characters in preview | During formatting in frontend/backend |
+| Importance score decay over time | Applied during search ranking |
+| Only owner can delete memory | Checked in `MemoryManager.delete()` using `user_id` |
+| Confirmation required for bulk delete | Enforced in CLI command logic |
-Enforced via scheduled cleanup job.
+### 5.4 Technical Implementation Details
-#### Access Control Rules
-Currently based on:
-- `user_id` (required)
-- `agent_id` (optional filter)
-- Future: RBAC roles (planned)
+#### Asynchronous Architecture
+- All critical operations are `async fn`
+- Tokio runtime powers CLI, API, and MCP servers
+- Non-blocking I/O ensures responsiveness even under load
-All queries implicitly scoped to requester’s identity.
+#### Memory Intelligence Loop
+Uses LLM-driven updater to decide actions:
+```rust
+let decision = llm_client.prompt_with_schema::(
+ "Given these existing memories and new input, what should we do?",
+ context
+).await?;
+```
-### 5.4 Technical Implementation Details
+#### Internationalization (i18n)
+- Built with Svelte stores and reactive `$t` function
+- Supports English, Chinese, Japanese
+- Fallback to English on missing keys
+- Language preference persisted in `localStorage`
-#### Core Components
-| File | Responsibility |
-|------|----------------|
-| `memory/manager.rs` | Primary orchestrator; exposes public API |
-| `llm/client.rs` | Handles authentication, retries, batching |
-| `vector_store/qdrant.rs` | Implements Qdrant gRPC client bindings |
-| `optimization_detector.rs` | Analyzes memory corpus for issues |
-| `optimizer.rs` | Executes refactoring plans |
-
-#### Concurrency Model
-- **Tokio Runtime**: Multi-threaded, work-stealing scheduler
-- **No Global Mutexes**: Per-operation locking
-- **Channel-Based Communication**: Between UI and worker threads
-
-#### Configuration System
-Built with:
-- `serde` for deserialization
-- `config.toml` as primary source
-- Environment variable overrides
-- Defaults via `impl Default` trait
-
-Supports hot-reload in development mode.
-
-#### Performance Optimization Strategies
-| Area | Technique |
-|------|----------|
-| Latency | Async I/O, connection pooling |
-| Throughput | Batch operations, bulk indexing |
-| Scalability | Stateless services, horizontal scaling |
-| Efficiency | Embedding caching, lazy loading |
-| Observability | Tracing spans, metrics export |
+#### Terminal UI (TARS Example)
+- Built with `ratatui` + `crossterm`
+- Three-panel layout: conversation (75%), input (25%), logs (right sidebar)
+- Real-time streaming responses with cursor animation
+- Sophisticated UTF-8 handling for cursor positioning
+
+#### Shutdown Sequence (Critical Reliability Feature)
+In `examples/cortex-mem-tars/src/main.rs`:
+```rust
+// After UI exits, continue processing memory saves
+drop(ui_tx); // Signal UI shutdown
+while let Ok(log) = log_rx.try_recv() {
+ process_log_for_memory_storage(&log);
+}
+// Ensure all pending memory operations complete
+```
-Planned enhancements:
-- Redis cache layer for frequent queries
-- Background embedding queue
-- Incremental optimization (vs full scan)
+> ✅ **Reliability Insight**: This design guarantees no memory loss due to premature termination.
---
## Conclusion
-The **cortex-mem** system delivers a robust, extensible framework for AI agent memory management. Its core workflows—memory management, search, and optimization—are deeply integrated, consistently implemented, and resilient to failure. The architecture promotes reuse through a shared core engine while supporting diverse frontends and integration points.
+The **Cortex-Mem** system delivers a robust, extensible framework for managing AI agent memories across diverse usage scenarios. Its architecture emphasizes:
+
+- **Modularity**: Clear separation between access interfaces and core logic
+- **Resilience**: Comprehensive error handling, graceful degradation, and safe shutdown
+- **Intelligence**: LLM-powered content understanding and autonomous optimization
+- **Observability**: Rich logging, monitoring endpoints, and interactive dashboards
-This document serves as a complete guide for developers, operators, and researchers working with the system, providing both high-level understanding and deep technical insight into its operation.
+This documentation provides full operational visibility into the system’s workflows, enabling developers, operators, and integrators to effectively deploy, maintain, and extend its capabilities.
-**Generated from research materials as of 2025-12-18 11:29:14 UTC**
+**Generated on**: 2025-12-30 19:19:37 UTC
+**Documentation Version**: 1.0
+**System Name**: Cortex-Mem
+**Primary Users**: AI Agents, Developers, System Administrators
\ No newline at end of file
diff --git a/litho.docs/4.Deep-Exploration/Access Interface Domain.md b/litho.docs/4.Deep-Exploration/Access Interface Domain.md
new file mode 100644
index 0000000..a3a4a20
--- /dev/null
+++ b/litho.docs/4.Deep-Exploration/Access Interface Domain.md
@@ -0,0 +1,422 @@
+# Technical Documentation: Access Interface Domain
+
+**Generation Time:** 2025-12-30 11:26:39 (UTC)
+**Document Version:** 1.0
+**System:** Cortex-Mem – AI Agent Memory Management System
+
+---
+
+## 1. Introduction
+
+The **Access Interface Domain** in the `cortex-mem` system provides multiple entry points for interacting with the persistent memory management capabilities of AI agents. It enables diverse user types—including developers, system administrators, and intelligent software agents—to store, retrieve, search, and optimize memories through tailored interfaces.
+
+This domain serves as the primary interaction layer between end users/agents and the core memory engine (`cortex-mem-core`), abstracting complex operations into accessible protocols while maintaining consistency across different access methods.
+
+### Key Objectives
+- Support heterogeneous integration scenarios (CLI, API, agent tools, UI)
+- Provide consistent behavior via centralized configuration
+- Enable both human and machine-driven interactions
+- Facilitate monitoring, debugging, and operational control
+
+---
+
+## 2. Architecture Overview
+
+The Access Interface Domain follows a **multi-interface facade pattern**, where each sub-interface acts as a specialized gateway to the shared business logic implemented in `cortex-mem-core`. All interfaces depend directly on the `MemoryManager` for executing memory operations.
+
+```mermaid
+graph TD
+ A[Access Interface Domain] --> B[CLI Interface]
+ A --> C[HTTP API Service]
+ A --> D[MCP Protocol Interface]
+ A --> E[Web Dashboard]
+
+ B -->|Uses| Core[cortex-mem-core]
+ C -->|Uses| Core
+ D -->|Uses| Core
+ E -->|API Calls| C
+ E -->|Direct Use| Core
+
+ style A fill:#2196F3,stroke:#1976D2,color:white
+ style Core fill:#4CAF50,stroke:#388E3C,color:white
+```
+
+> **Note**: The Web Dashboard primarily communicates via the HTTP API but may also use direct core access for advanced features.
+
+### Interaction Flow Pattern
+```mermaid
+sequenceDiagram
+ participant User
+ participant CLI as CLI Interface
+ participant HTTP_API as HTTP API Service
+ participant MCP as MCP Protocol Interface
+ participant Web_Dashboard as Web Dashboard
+ participant Memory_System as MemoryManager (Core)
+
+ User->>CLI: Execute command (e.g., add, search)
+ CLI->>Memory_System: Forward request
+ Memory_System-->>CLI: Return result
+ CLI-->>User: Print output
+
+ User->>HTTP_API: Send HTTP request
+ HTTP_API->>Memory_System: Handle route & forward
+ Memory_System-->>HTTP_API: Response
+ HTTP_API-->>User: JSON response
+
+ AI_Agent->>MCP: Invoke MCP tool (store/query)
+ MCP->>Memory_System: Process call
+ Memory_System-->>MCP: Result
+ MCP-->>AI_Agent: Return structured data
+
+ User->>Web_Dashboard: Browser navigation
+ Web_Dashboard->>HTTP_API: Fetch data via REST
+ HTTP_API-->>Web_Dashboard: JSON payload
+ Web_Dashboard-->>User: Rendered UI
+```
+
+---
+
+## 3. Submodules and Implementation Details
+
+The Access Interface Domain consists of four distinct submodules, each designed for specific usage patterns and target audiences.
+
+### 3.1 CLI Interface
+
+#### Purpose
+Provides a command-line tool for direct interaction by developers and operators. Ideal for scripting, batch operations, and local development.
+
+#### Entry Point
+- **File**: `cortex-mem-cli/src/main.rs`
+- **Framework**: [Clap](https://crates.io/crates/clap) for declarative argument parsing
+
+#### Supported Commands
+| Command | Functionality |
+|--------|---------------|
+| `add` | Store new memory with metadata |
+| `search` | Semantic + metadata-filtered retrieval |
+| `list` | List memories with filters |
+| `delete` | Remove memory by ID |
+| `optimize` | Trigger optimization workflows |
+| `optimize-status` | Check ongoing job status |
+
+#### Code Structure
+```rust
+// Example: AddCommand execution flow
+pub async fn execute(
+ &self,
+ content: String,
+ user_id: Option,
+ agent_id: Option,
+ memory_type: String,
+) -> Result<(), Box> {
+ let metadata = build_metadata(user_id, agent_id, memory_type);
+
+ if is_conversation(&content) {
+ let messages = parse_conversation_content(&content, &user_id, &agent_id);
+ self.memory_manager.add_memory(&messages, metadata).await?;
+ } else {
+ self.memory_manager.store(content, metadata).await?;
+ }
+}
+```
+
+#### Conversation Parsing Logic
+Handles multi-turn dialogues from CLI input:
+- Detects lines starting with `User:` or `Assistant:`
+- Splits content into role-based messages
+- Falls back to single-user message if no roles detected
+
+> **Example Input**:
+```
+User: What's the capital of France?
+Assistant: The capital of France is Paris.
+```
+
+Parsed into two `Message` objects with appropriate roles.
+
+#### Initialization Sequence
+1. Initialize tracing (`tracing_subscriber`)
+2. Parse CLI arguments using Clap
+3. Load config from `config.toml`
+4. Auto-detect vector store and LLM client
+5. Create `MemoryManager`
+6. Route command to handler
+
+---
+
+### 3.2 HTTP API Service
+
+#### Purpose
+Exposes RESTful endpoints for programmatic access. Enables integration with external applications, microservices, and web clients.
+
+#### Entry Point
+- **File**: `cortex-mem-service/src/main.rs`
+- **Framework**: [Axum](https://crates.io/crates/axum) for routing and middleware
+
+#### Endpoint Summary
+| Method | Path | Description |
+|-------|------|-------------|
+| GET | `/health` | System health check |
+| POST | `/memories` | Create memory |
+| GET | `/memories` | List memories |
+| POST | `/memories/search` | Search memories (semantic + filters) |
+| GET | `/memories/{id}` | Retrieve specific memory |
+| PUT | `/memories/{id}` | Update memory |
+| DELETE | `/memories/{id}` | Delete memory |
+| POST | `/optimization` | Start optimization job |
+| GET | `/optimization/{job_id}` | Get optimization status |
+| GET | `/llm/status` | LLM service status |
+
+#### Request Handling Pattern
+```rust
+pub async fn create_memory(
+ State(state): State,
+ Json(request): Json,
+) -> Result, (StatusCode, Json)> {
+ let metadata = build_metadata_from_request(&request);
+
+ if is_conversation_request(&request.content) {
+ let messages = parse_conversation_content(
+ &request.content,
+ &request.user_id,
+ &request.agent_id
+ );
+ match state.memory_manager.add_memory(&messages, metadata).await { ... }
+ } else {
+ match state.memory_manager.store(request.content, metadata).await { ... }
+ }
+}
+```
+
+#### Shared State Model
+```rust
+#[derive(Clone)]
+pub struct AppState {
+ pub memory_manager: Arc,
+ pub optimization_jobs: Arc>>,
+}
+```
+
+All routes receive this state via Axum’s dependency injection mechanism.
+
+#### Middleware
+- CORS enabled permissively during development
+- Structured error handling with standardized responses
+- Tracing integration for observability
+
+---
+
+### 3.3 MCP Protocol Interface
+
+#### Purpose
+Implements the **Memory Control Protocol (MCP)** for seamless integration with AI agents. Allows agents to treat memory operations as callable tools.
+
+#### Entry Point
+- **Binary**: `cortex-mem-mcp/src/main.rs`
+- **Library**: `cortex-mem-mcp/src/lib.rs`
+- **Transport**: Standard I/O (stdio) for compatibility with agent frameworks
+
+#### Implemented Tools
+| Tool Name | Function |
+|----------|---------|
+| `store_memory` | Save a new memory |
+| `query_memory` | Search memories semantically |
+| `list_memories` | List memories with filters |
+| `get_memory` | Retrieve memory by ID |
+
+#### Server Handler Implementation
+```rust
+impl MemoryMcpService {
+ async fn store_memory(
+ &self,
+ arguments: &Map,
+ ) -> Result {
+ let payload = map_mcp_arguments_to_payload(arguments, &self.agent_id);
+ match self.operations.store_memory(payload).await {
+ Ok(response) => Ok(CallToolResult::success(vec![Content::text(
+ serde_json::to_string_pretty(&response).unwrap()
+ )])),
+ Err(e) => Err(self.tools_error_to_mcp_error(e))
+ }
+ }
+
+ // Similar implementations for query_memory, list_memories, get_memory
+}
+```
+
+#### Initialization
+- Loads configuration from default or specified path
+- Initializes `MemoryManager` with auto-detected components
+- Sets up `MemoryOperations` wrapper
+- Serves over stdio using `rmcp::transport::stdio`
+
+#### Integration Example (Agent Side)
+An AI agent can invoke:
+```json
+{
+ "tool": "store_memory",
+ "arguments": {
+ "content": "The user prefers vegan meals.",
+ "user_id": "usr_123",
+ "memory_type": "factual"
+ }
+}
+```
+
+And receive confirmation of successful storage.
+
+---
+
+### 3.4 Web Dashboard
+
+#### Purpose
+Provides a visual interface for monitoring, managing, and analyzing memory collections. Designed for system administrators and developers needing insight into memory quality and performance.
+
+#### Stack
+- **Frontend Framework**: [Svelte](https://svelte.dev/)
+- **Backend Server**: [Elysia](https://elysiajs.com/) (TypeScript)
+- **Routing**: File-based SvelteKit routing
+- **Styling**: Tailwind CSS
+
+#### Entry Points
+- **Server**: `cortex-mem-insights/src/server/index.ts`
+- **Layout**: `cortex-mem-insights/src/routes/+layout.svelte`
+
+#### Layout Component (`+layout.svelte`)
+```svelte
+
+
+
+
+
+
+
+
+
+```
+
+#### Features
+- Real-time system health visualization
+- Memory search and browsing
+- Optimization job tracking
+- Statistics dashboard (duplicates, retention, usage trends)
+- Internationalization support via `$lib/i18n`
+
+#### API Integration
+Communicates with the backend via:
+- `/api/memory/*` – CRUD and search operations
+- `/api/optimization/*` – Optimization lifecycle
+- `/api/system/*` – Health and configuration
+
+Built using modular Elysia plugins:
+```ts
+.use(memoryRoutes)
+.use(optimizationRoutes)
+.use(systemRoutes)
+```
+
+---
+
+## 4. Cross-Cutting Concerns
+
+### 4.1 Configuration Management
+All interfaces share a common configuration model defined in `cortex-mem-config`, loaded from `config.toml`.
+
+Key settings include:
+- Qdrant connection details
+- LLM provider (OpenAI) credentials
+- Server host/port (for HTTP/MCP services)
+- Logging level
+- Memory retention policies
+
+Each interface reads the same config file, ensuring uniform behavior.
+
+### 4.2 Error Handling and Logging
+- Unified logging via `tracing` crate
+- Structured JSON logs for machine readability
+- Human-friendly CLI output formatting
+- HTTP error codes and standardized error payloads
+- MCP-compliant error reporting
+
+### 4.3 Security Considerations
+- No built-in authentication in current version (assumes trusted environment)
+- Sensitive data protection relies on transport-level security
+- Future roadmap likely includes API keys and RBAC
+
+---
+
+## 5. Integration with Core Domains
+
+The Access Interface Domain depends heavily on other domains:
+
+| From | To | Type | Purpose |
+|------|----|------|--------|
+| Access Interface | Memory Management | Service Call | Execute CRUD, search, optimization |
+| Access Interface | Configuration Management | Configuration Dependency | Load runtime settings |
+| Access Interface | LLM Integration | Indirect | Embedding generation, analysis |
+| Access Interface | Storage Integration | Indirect | Vector persistence |
+
+> **Dependency Strength**: 9.5 (Very Strong)
+
+All interfaces delegate actual memory processing to `MemoryManager`, adhering to the principle of separation of concerns.
+
+---
+
+## 6. Usage Scenarios
+
+| User Type | Preferred Interface | Use Case |
+|---------|---------------------|----------|
+| Developer | CLI / HTTP API | Scripting, testing, integration |
+| AI Agent | MCP Protocol | Contextual memory access during reasoning |
+| Operator | Web Dashboard | Monitoring, maintenance, optimization |
+| Application | HTTP API | Embedded agent memory layer |
+
+---
+
+## 7. Development and Extension Guide
+
+### Adding a New Command (CLI)
+1. Define command struct in `commands/mod.rs`
+2. Implement `execute()` method calling `MemoryManager`
+3. Add variant to `Commands` enum in `main.rs`
+4. Wire up in `main()` match block
+
+### Adding a New API Endpoint
+1. Define handler function in `handlers.rs`
+2. Add route in `main.rs` router
+3. Define request/response models in `models.rs`
+4. Ensure proper error mapping
+
+### Extending MCP Tools
+1. Add new method to `MemoryMcpService`
+2. Register in `ServerHandler` trait implementation
+3. Update tool definitions via `get_mcp_tool_definitions()`
+
+---
+
+## 8. Conclusion
+
+The **Access Interface Domain** is a critical component of the `cortex-mem` architecture, enabling flexible and secure interaction with AI agent memory systems. By providing four complementary interfaces—CLI, HTTP API, MCP, and Web Dashboard—it supports a wide range of use cases from automated agent workflows to human-operated administration.
+
+Its design emphasizes:
+- **Consistency**: Shared core logic ensures uniform behavior
+- **Extensibility**: Modular structure allows adding new interfaces
+- **Interoperability**: Supports both human and machine consumers
+- **Observability**: Rich logging and monitoring capabilities
+
+Future enhancements could include:
+- Authentication and authorization layers
+- WebSockets for real-time updates
+- gRPC interface for high-performance integrations
+- Plugin system for custom interface extensions
+
+This domain exemplifies modern API-first design principles applied to AI infrastructure, making persistent memory accessible, reliable, and maintainable.
\ No newline at end of file
diff --git a/litho.docs/4.Deep-Exploration/Configuration Management Domain.md b/litho.docs/4.Deep-Exploration/Configuration Management Domain.md
new file mode 100644
index 0000000..6c9cac9
--- /dev/null
+++ b/litho.docs/4.Deep-Exploration/Configuration Management Domain.md
@@ -0,0 +1,444 @@
+# Configuration Management Domain Technical Documentation
+
+## 1. Overview
+
+The Configuration Management Domain serves as the centralized configuration system for the Cortex-Mem platform, providing a unified approach to manage application settings across all components. This domain ensures consistent behavior and proper initialization of the memory management system by defining comprehensive configuration schemas and implementing robust loading, validation, and auto-detection mechanisms.
+
+As an Infrastructure Domain with high importance (8.0/10), the Configuration Management system acts as the single source of truth for settings that govern various subsystems including vector database connectivity, LLM integration, HTTP server parameters, embedding services, and memory management policies. The system is implemented primarily in Rust with supporting Python utilities for validation, following a modular design that enables extensibility while maintaining type safety.
+
+## 2. Architecture and Design
+
+### 2.1 Component Structure
+
+The Configuration Management Domain consists of three primary components:
+
+- **Config Structure**: Defines the schema and data types for configuration through Rust structs with serde serialization
+- **Config Loading**: Handles file parsing and error propagation using TOML format
+- **Config Validation**: Ensures configuration integrity through both structural and content validation
+
+The core implementation resides in `cortex-mem-config/src/lib.rs`, which exports a comprehensive set of configuration structs that are consumed by other components during initialization.
+
+### 2.2 Key Data Structures
+
+The configuration system is built around a hierarchical structure of Rust structs that represent different subsystem configurations:
+
+```rust
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Config {
+ pub qdrant: QdrantConfig,
+ pub llm: LLMConfig,
+ pub server: ServerConfig,
+ pub embedding: EmbeddingConfig,
+ pub memory: MemoryConfig,
+ pub logging: LoggingConfig,
+}
+```
+
+Each subsystem has its own dedicated configuration struct with specific fields relevant to its operation:
+
+- **QdrantConfig**: Manages vector database connection parameters
+- **LLMConfig**: Handles language model service credentials and behavior
+- **ServerConfig**: Controls HTTP server binding and CORS policies
+- **EmbeddingConfig**: Configures embedding generation service
+- **MemoryConfig**: Defines memory management policies and thresholds
+- **LoggingConfig**: Specifies logging behavior and output destinations
+
+### 2.3 Design Principles
+
+The configuration system adheres to several key design principles:
+
+1. **Type Safety**: Leverages Rust's strong typing system to prevent invalid configurations at compile time
+2. **Default Values**: Implements sensible defaults through the `Default` trait for optional parameters
+3. **Extensibility**: Supports adding new configuration sections without breaking existing code
+4. **Validation**: Provides multi-layered validation to ensure configuration correctness
+5. **Auto-detection**: Includes intelligent features like automatic embedding dimension detection
+
+## 3. Implementation Details
+
+### 3.1 Configuration Schema
+
+The configuration schema is defined using Rust's derive macros for Serde, enabling seamless serialization between TOML files and in-memory data structures. The main `Config` struct composes multiple subsystem configurations, creating a comprehensive hierarchy that covers all aspects of the system.
+
+Key implementation features include:
+
+- **Serde Integration**: Uses `#[derive(Serialize, Deserialize)]` for automatic TOML parsing
+- **Error Handling**: Employs `anyhow::Result` for rich error propagation with context
+- **Path Abstraction**: Accepts generic path types through `AsRef` for flexibility
+- **Clone Support**: Implements `Clone` trait to enable configuration sharing across components
+
+### 3.2 Default Values Implementation
+
+The system implements default values for optional parameters through Rust's `Default` trait, ensuring that required functionality works even when users don't specify all settings:
+
+```rust
+impl Default for MemoryConfig {
+ fn default() -> Self {
+ MemoryConfig {
+ max_memories: 10000,
+ similarity_threshold: 0.65,
+ max_search_results: 50,
+ memory_ttl_hours: None,
+ auto_summary_threshold: 32768,
+ auto_enhance: true,
+ deduplicate: true,
+ merge_threshold: 0.75,
+ search_similarity_threshold: Some(0.70),
+ }
+ }
+}
+
+impl Default for LoggingConfig {
+ fn default() -> Self {
+ LoggingConfig {
+ enabled: false,
+ log_directory: "logs".to_string(),
+ level: "info".to_string(),
+ }
+ }
+}
+```
+
+This approach provides sensible defaults while still allowing users to override them through the configuration file.
+
+### 3.3 Auto-detection Mechanism
+
+One of the advanced features of the configuration system is the ability to auto-detect embedding dimensions when not explicitly specified. This is particularly valuable because embedding dimensions vary between different LLM models and services.
+
+The auto-detection workflow is implemented in `cortex-mem-core/src/init/mod.rs`:
+
+1. When `embedding_dim` is not specified in the Qdrant configuration
+2. A temporary LLM client is created using the provided API credentials
+3. A test embedding is generated for a sample text ("test")
+4. The dimension of the resulting embedding vector is detected
+5. The configuration is updated with the detected dimension
+
+```rust
+pub async fn create_auto_config(
+ base_config: &QdrantConfig,
+ llm_client: &dyn LLMClient,
+) -> Result {
+ let mut config = base_config.clone();
+
+ if config.embedding_dim.is_none() {
+ info!("Auto-detecting embedding dimension for configuration...");
+ let test_embedding = llm_client.embed(\"test\").await?;
+ let detected_dim = test_embedding.len();
+ info!(\"Detected embedding dimension: {}\", detected_dim);
+ config.embedding_dim = Some(detected_dim);
+ }
+
+ Ok(config)
+}
+```
+
+This feature eliminates configuration errors related to mismatched embedding dimensions and improves user experience by reducing setup complexity.
+
+## 4. Configuration Workflow
+
+### 4.1 Configuration Loading Process
+
+The configuration loading process follows a well-defined sequence:
+
+```mermaid
+graph TD
+ A[Start] --> B{Config File Exists?}
+ B -->|No| C[Return Error]
+ B -->|Yes| D[Parse TOML File]
+ D --> E[Validate Required Sections]
+ E --> F[Validate Required Fields]
+ F --> G[Load Subsystem Configs]
+ G --> H[Apply Default Values if Needed]
+ H --> I[Auto-Detect Embedding Dimension?]
+ I -->|Yes| J[Infer from LLM Client]
+ J --> K[Create Final Config]
+ I -->|No| K
+ K --> L[Initialize Components]
+ L --> M[End]
+```
+
+### 4.2 Sequence of Operations
+
+The detailed sequence of operations during configuration loading:
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant ConfigModule
+ participant FileSystem
+ participant Validator
+ participant LLMClient
+ participant VectorStore
+
+ User->>ConfigModule: Request config load
+ ConfigModule->>FileSystem: Read config.toml
+ FileSystem-->>ConfigModule: Return file content
+ ConfigModule->>ConfigModule: Parse TOML to Config struct
+ ConfigModule->>Validator: Validate required sections/fields
+ Validator-->>ConfigModule: Validation result
+ alt If embedding_dim not specified
+ ConfigModule->>LLMClient: Create temporary client
+ LLMClient-->>ConfigModule: Return client
+ ConfigModule->>LLMClient: Request test embedding
+ LLMClient-->>ConfigModule: Return embedding dimension
+ ConfigModule->>ConfigModule: Update config with detected dimension
+ end
+ ConfigModule->>VectorStore: Initialize with config
+ VectorStore-->>ConfigModule: Return initialized store
+ ConfigModule-->>User: Return ready-to-use components
+```
+
+## 5. Configuration File Format
+
+### 5.1 TOML Configuration Structure
+
+The system uses TOML (Tom's Obvious, Minimal Language) as the configuration file format due to its readability and support for complex data structures. The main configuration file (`config.toml`) contains the following sections:
+
+```toml
+# Main configuration for the cortex-mem system
+
+[qdrant]
+url = "http://localhost:6334"
+collection_name = "cortex-mem-hewlett_drawn"
+# embedding_dim = 1024 # Optional, will be auto-detected if not specified
+timeout_secs = 30
+
+[llm]
+api_base_url = "https://wanqing-api.corp.kuaishou.com/api/gateway/v1/endpoints"
+api_key = "fs2wzco3o7haz38df1jo4vavnvauxtuz3f0b"
+model_efficient = "ep-i4abhq-1764595896785685523"
+temperature = 0.1
+max_tokens = 4096
+
+[server]
+host = "0.0.0.0"
+port = 3000
+cors_origins = ["*"]
+
+[embedding]
+api_base_url = "https://wanqing-api.corp.kuaishou.com/api/gateway/v1/endpoints"
+api_key = "fs2wzco3o7haz38df1jo4vavnvauxtuz3f0b"
+model_name = "ep-9kf01g-1762237999831608613"
+batch_size = 10
+timeout_secs = 30
+
+[memory]
+max_memories = 10000
+max_search_results = 50
+# memory_ttl_hours = 24 # Optional
+auto_summary_threshold = 4096
+auto_enhance = true
+deduplicate = true
+similarity_threshold = 0.65
+merge_threshold = 0.75
+search_similarity_threshold = 0.5
+
+[logging]
+enabled = true
+log_directory = "logs"
+level = "debug"
+```
+
+### 5.2 Required vs. Optional Parameters
+
+The configuration system distinguishes between required and optional parameters:
+
+**Required Parameters:**
+- `qdrant.url`: Vector database endpoint URL
+- `qdrant.collection_name`: Name of the collection in Qdrant
+- `llm.api_base_url`: LLM service API endpoint
+- `llm.api_key`: Authentication key for LLM service
+- `llm.model_efficient`: Model identifier for efficient operations
+- `embedding.api_base_url`: Embedding service API endpoint
+- `embedding.api_key`: Authentication key for embedding service
+- `embedding.model_name`: Model identifier for embeddings
+
+**Optional Parameters with Defaults:**
+- `qdrant.embedding_dim`: Auto-detected if not specified
+- `memory.memory_ttl_hours`: No expiration if not specified
+- `memory.search_similarity_threshold`: Defaults to 0.70
+- `logging.enabled`: Defaults to false
+- `logging.level`: Defaults to "info"
+
+## 6. Validation System
+
+### 6.1 Multi-Layered Validation Approach
+
+The configuration system employs a multi-layered validation strategy to ensure configuration integrity:
+
+1. **Structural Validation**: Performed automatically by Serde during TOML deserialization
+2. **Content Validation**: Implemented through custom Python utilities in `examples/lomoco-evaluation/src/cortex_mem/config_utils.py`
+3. **Runtime Validation**: Conducted during component initialization
+
+### 6.2 Validation Implementation
+
+The Python-based validation utilities provide comprehensive checking of configuration completeness:
+
+```python
+def validate_config(config_path: str) -> bool:
+ """Validate that config file exists and has required settings."""
+ if not os.path.exists(config_path):
+ print(f"Config file not found: {config_path}")
+ return False
+
+ try:
+ with open(config_path, 'r') as f:
+ content = f.read()
+
+ # Check for required sections
+ required_sections = ["llm", "embedding", "qdrant", "memory"]
+ missing_sections = []
+
+ for section in required_sections:
+ if f"[{section}]" not in content:
+ missing_sections.append(section)
+
+ if missing_sections:
+ print(f"Missing required sections in config: {missing_sections}")
+ return False
+
+ # Check for required fields in each section
+ import toml
+ config_data = toml.load(config_path)
+
+ # Check llm section
+ if "llm" in config_data:
+ llm = config_data["llm"]
+ required_llm_fields = ["api_key", "api_base_url", "model_efficient"]
+ missing_llm = [field for field in required_llm_fields if field not in llm]
+ if missing_llm:
+ print(f"Missing fields in [llm] section: {missing_llm}")
+ return False
+
+ # Similar checks for embedding, qdrant, and other sections
+ return True
+
+ except Exception as e:
+ print(f"Error validating config: {e}")
+ return False
+```
+
+The validation system checks for:
+- Existence of the configuration file
+- Presence of required sections (`[llm]`, `[embedding]`, `[qdrant]`, `[memory]`)
+- Required fields within each section
+- Valid data types and formats
+
+### 6.3 OpenAI-Specific Validation
+
+A specialized validation function checks OpenAI configuration specifically:
+
+```python
+def check_openai_config(config_path: str) -> bool:
+ """Check if OpenAI configuration is properly set."""
+ try:
+ import toml
+ config_data = toml.load(config_path)
+
+ # Check llm section
+ if "llm" not in config_data:
+ print("Missing [llm] section in config")
+ return False
+
+ llm = config_data["llm"]
+ if "api_key" not in llm or not llm["api_key"]:
+ print("OpenAI API key not set in [llm] section")
+ return False
+
+ if "api_base_url" not in llm or not llm["api_base_url"]:
+ print("OpenAI API base URL not set in [llm] section")
+ return False
+
+ # Check embedding section
+ if "embedding" not in config_data:
+ print("Missing [embedding] section in config")
+ return False
+
+ embedding = config_data["embedding"]
+ if "api_key" not in embedding or not embedding["api_key"]:
+ print("OpenAI API key not set in [embedding] section")
+ return False
+
+ return True
+
+ except Exception as e:
+ print(f"Error checking OpenAI config: {e}")
+ return False
+```
+
+## 7. Integration with Other Domains
+
+### 7.1 Configuration Dependencies
+
+The Configuration Management Domain serves as a foundational component that other domains depend on for their operation:
+
+| Dependent Domain | Configuration Usage |
+|------------------|----------------------|
+| **Storage Integration Domain** | Uses Qdrant configuration for vector database connectivity |
+| **LLM Integration Domain** | Uses LLM and embedding configurations for service authentication and behavior |
+| **Memory Optimization Domain** | Uses memory configuration for optimization thresholds and strategies |
+| **Access Interface Domain** | Uses server and logging configurations for interface behavior |
+
+### 7.2 Initialization Flow
+
+During system startup, the configuration system plays a critical role in the initialization workflow:
+
+```mermaid
+graph TD
+ A[Load Configuration] --> B[Initialize Tracing & Logging]
+ B --> C{Auto-detect Components}
+ C --> D[Detect Vector Store]
+ C --> E[Detect LLM Client]
+ C --> F[Determine Embedding Dimension]
+
+ D --> G[Create MemoryManager]
+ E --> G
+ F --> G
+
+ G --> H[Expose Interfaces]
+ H --> I[CLI Interface]
+ H --> J[HTTP API Service]
+ H --> K[MCP Server]
+ H --> L[Web Dashboard]
+```
+
+The configuration is loaded first, then used to initialize tracing and logging systems, followed by auto-detection of components based on the provided settings.
+
+## 8. Best Practices and Recommendations
+
+### 8.1 Configuration Management Best Practices
+
+1. **Environment-Specific Configuration**: Use different configuration files for development, testing, and production environments
+2. **Secret Management**: Never commit API keys to version control; use environment variables or secret management tools
+3. **Version Control**: Keep configuration files under version control (without secrets) to track changes
+4. **Documentation**: Document all configuration options and their effects
+5. **Testing**: Validate configuration changes in non-production environments before deployment
+
+### 8.2 Security Considerations
+
+1. **API Key Protection**: Ensure API keys are stored securely and have appropriate access controls
+2. **Network Security**: Use HTTPS for all external service communications
+3. **Input Validation**: Validate all configuration inputs to prevent injection attacks
+4. **Least Privilege**: Configure API keys with minimal required permissions
+5. **Audit Logging**: Enable logging to monitor configuration changes and access patterns
+
+### 8.3 Performance Optimization
+
+1. **Caching**: Cache configuration data in memory to avoid repeated file I/O
+2. **Connection Pooling**: Use connection pooling for database and API connections
+3. **Batch Processing**: Configure appropriate batch sizes for embedding generation
+4. **Timeout Settings**: Set reasonable timeouts to prevent hanging operations
+5. **Resource Limits**: Configure memory limits to prevent resource exhaustion
+
+## 9. Future Enhancements
+
+Potential improvements to the Configuration Management Domain include:
+
+1. **Dynamic Reloading**: Support for reloading configuration without restarting the system
+2. **Remote Configuration**: Integration with configuration servers for centralized management
+3. **Configuration Versioning**: Support for versioned configurations and rollback capabilities
+4. **Schema Validation**: JSON Schema-based validation for additional integrity checks
+5. **Environment Variables**: Enhanced support for environment variable overrides
+6. **Configuration Templates**: Support for template-based configuration generation
+7. **Validation Rules Engine**: More sophisticated validation rules based on inter-parameter dependencies
+
+These enhancements would further improve the flexibility, security, and maintainability of the configuration system while supporting more complex deployment scenarios.
\ No newline at end of file
diff --git a/litho.docs/4.Deep-Exploration/LLM Integration Domain.md b/litho.docs/4.Deep-Exploration/LLM Integration Domain.md
new file mode 100644
index 0000000..43127d6
--- /dev/null
+++ b/litho.docs/4.Deep-Exploration/LLM Integration Domain.md
@@ -0,0 +1,335 @@
+# LLM Integration Domain Technical Documentation
+
+## 1. Overview
+
+The **LLM Integration Domain** is a core component of the Cortex-Mem system responsible for managing interactions with Large Language Models (LLMs) to extract insights from content and enable intelligent decision-making for memory operations. This domain serves as the cognitive engine that transforms unstructured text into structured knowledge, enabling advanced memory management capabilities.
+
+This documentation provides comprehensive technical details about the architecture, implementation, and functionality of the LLM Integration Domain based on the analysis of source code and system research materials.
+
+### Key Characteristics
+- **Domain Type**: Core Business Domain
+- **Importance Score**: 9.0/10.0
+- **Complexity Level**: High (8.5/10.0)
+- **Primary Responsibility**: Enabling intelligent processing of memory content through LLM-powered analysis, extraction, and decision-making
+
+```mermaid
+graph TD
+ A[LLM Client] --> B[Information Extraction]
+ A --> C[Memory Intelligence]
+ B --> D[Extract Structured Facts]
+ B --> E[Extract Keywords]
+ B --> F[Extract Entities]
+ C --> G[Analyze Content]
+ C --> H[Assess Similarity]
+ C --> I[Recommend Operations]
+ A --> J[Health Check]
+ A --> K[Rate Limiting]
+```
+
+## 2. Architecture and Components
+
+The LLM Integration Domain consists of three primary sub-modules that work together to provide comprehensive LLM capabilities:
+
+### 2.1 LLM Client Module
+
+The `LLMClient` is the foundational component that manages communication with external LLM services, primarily OpenAI. It implements a robust client interface with support for both traditional text completion and modern structured extraction capabilities.
+
+#### Key Features:
+- **Multi-capability Interface**: Supports text completion, embedding generation, and structured data extraction
+- **Fallback Mechanisms**: Implements graceful degradation when structured extraction fails
+- **Rate Limiting**: Includes built-in rate limiting (1 second delay between batch operations)
+- **Health Monitoring**: Provides health checking through embedding requests
+- **Concurrent Operation**: Designed to be cloned and used concurrently in asynchronous contexts
+
+#### Trait Definition:
+```rust
+#[async_trait]
+pub trait LLMClient: Send + Sync + dyn_clone::DynClone {
+ // Core capabilities
+ async fn complete(&self, prompt: &str) -> Result;
+ async fn embed(&self, text: &str) -> Result>;
+ async fn embed_batch(&self, texts: &[String]) -> Result>>;
+
+ // Information extraction
+ async fn extract_keywords(&self, content: &str) -> Result>;
+ async fn summarize(&self, content: &str, max_length: Option) -> Result;
+
+ // Health and monitoring
+ async fn health_check(&self) -> Result;
+
+ // Structured extraction methods
+ async fn extract_structured_facts(&self, prompt: &str) -> Result;
+ async fn extract_detailed_facts(&self, prompt: &str) -> Result;
+ async fn classify_memory(&self, prompt: &str) -> Result;
+ async fn score_importance(&self, prompt: &str) -> Result;
+}
+```
+
+#### Implementation Details:
+The `OpenAILLMClient` implementation uses the RIG framework to interact with OpenAI services, providing both completion and embedding models. The client is configured through centralized configuration (`LLMConfig` and `EmbeddingConfig`) which specifies API keys, endpoints, model names, temperature settings, and token limits.
+
+Key architectural decisions include:
+- **Separation of Concerns**: Different models are used for completion vs. embedding tasks
+- **Error Resilience**: Comprehensive error handling with fallback mechanisms
+- **Performance Optimization**: Batch processing with controlled rate limiting
+- **Debug Support**: Conditional sleep statements in debug builds to prevent rate limiting issues during development
+
+### 2.2 Information Extraction Module
+
+The Information Extraction module leverages the LLM Client to transform unstructured content into structured knowledge representations. This module focuses on extracting specific types of information from memory content.
+
+#### Primary Capabilities:
+- **Fact Extraction**: Identifies and extracts important facts from conversations
+- **Keyword Identification**: Extracts key terms and phrases from content
+- **Entity Recognition**: Detects named entities such as people, organizations, and locations
+- **Language Detection**: Automatically detects the language of input content
+- **Conversation Analysis**: Analyzes conversation dynamics including topics, sentiment, and user intent
+
+#### Data Structures:
+The module defines several structured response types using Serde serialization and JSON Schema generation:
+
+```rust
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+pub struct StructuredFactExtraction {
+ pub facts: Vec,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+pub struct DetailedFactExtraction {
+ pub facts: Vec,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+pub struct KeywordExtraction {
+ pub keywords: Vec,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+pub struct EntityExtraction {
+ pub entities: Vec,
+}
+```
+
+#### Processing Workflow:
+1. **Prompt Construction**: Builds specialized prompts for different extraction tasks
+2. **Structured Extraction**: Uses RIG's extractor_completions_api for reliable structured output
+3. **Fallback Processing**: Falls back to traditional completion if structured extraction fails
+4. **Response Parsing**: Parses and validates the structured responses
+5. **Result Normalization**: Standardizes the extracted information for downstream use
+
+The module implements sophisticated prompt engineering techniques, including:
+- Role-specific prompts for user vs. assistant messages
+- Context-aware extraction strategies
+- Language-preserving extraction (facts are returned in the same language as input)
+
+### 2.3 Memory Intelligence Module
+
+The Memory Intelligence module applies LLM analysis to make strategic decisions about memory operations. This module represents the highest level of cognitive processing in the system, using LLM insights to guide memory lifecycle management.
+
+#### Key Functions:
+- **Content Analysis**: Evaluates memory content for importance, relevance, and quality
+- **Similarity Assessment**: Determines semantic similarity between memories for deduplication
+- **Operation Recommendation**: Recommends optimal actions (create, update, merge, delete) for memory management
+- **Optimization Planning**: Generates plans for memory collection improvement
+
+#### Decision-Making Process:
+The module implements a sophisticated decision framework that considers multiple factors when recommending memory operations:
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant LLMClient
+ participant InformationExtraction
+ participant MemoryIntelligence
+
+ User->>LLMClient: Request text completion
+ LLMClient->>LLMClient: Process request with fallback mechanism
+ LLMClient-->>User: Return completion result
+
+ User->>LLMClient: Request structured extraction
+ LLMClient->>LLMClient: Use rig extractor or fallback to completion
+ LLMClient-->>User: Return structured data
+
+ InformationExtraction->>LLMClient: Extract keywords/facts/entities
+ LLMClient-->>InformationExtraction: Return extracted information
+
+ MemoryIntelligence->>LLMClient: Analyze content for memory decisions
+ LLMClient-->>MemoryIntelligence: Return analysis results
+```
+
+## 3. Integration Patterns
+
+### 3.1 Configuration Integration
+
+The LLM Integration Domain depends on the Configuration Management Domain for critical settings:
+
+```rust
+pub struct OpenAILLMClient {
+ completion_model: Agent,
+ completion_model_name: String,
+ embedding_model: OpenAIEmbeddingModel,
+ client: Client,
+}
+
+impl OpenAILLMClient {
+ pub fn new(llm_config: &LLMConfig, embedding_config: &EmbeddingConfig) -> Result {
+ let client = Client::builder(&llm_config.api_key)
+ .base_url(&llm_config.api_base_url)
+ .build();
+
+ // Configuration-driven model selection
+ let completion_model: Agent = client
+ .completion_model(&llm_config.model_efficient)
+ .completions_api()
+ .into_agent_builder()
+ .temperature(llm_config.temperature as f64)
+ .max_tokens(llm_config.max_tokens as u64)
+ .build();
+ }
+}
+```
+
+Configuration parameters include:
+- API keys and base URLs
+- Model selection (efficient vs. powerful)
+- Temperature and token limits
+- Embedding model specifications
+
+### 3.2 Interaction with Other Domains
+
+The LLM Integration Domain interacts with several other domains in the system:
+
+#### With Memory Management Domain:
+- Provides embedding generation for semantic search
+- Enables content analysis for memory classification
+- Supports intelligent retrieval through semantic understanding
+
+#### With Memory Optimization Domain:
+- Powers duplicate detection through similarity assessment
+- Enables quality scoring for optimization decisions
+- Supports merging recommendations based on content analysis
+
+#### With Access Interface Domain:
+- Processes natural language queries from CLI
+- Interprets search requests from HTTP API
+- Handles agent commands through MCP interface
+
+## 4. Technical Implementation Details
+
+### 4.1 Error Handling and Resilience
+
+The implementation includes comprehensive error handling strategies:
+
+```rust
+async fn extract_keywords(&self, content: &str) -> Result> {
+ let prompt = self.build_keyword_prompt(content);
+
+ match self.extract_keywords_structured(&prompt).await {
+ Ok(keyword_extraction) => {
+ debug!("Extracted {} keywords using rig extractor",
+ keyword_extraction.keywords.len());
+ Ok(keyword_extraction.keywords)
+ }
+ Err(e) => {
+ // Fallback to traditional method if extractor fails
+ debug!("Rig extractor failed, falling back: {}", e);
+
+ #[cfg(debug_assertions)]
+ tokio::time::sleep(std::time::Duration::from_secs(1)).await;
+
+ let response = self.complete(&prompt).await?;
+ let keywords = self.parse_keywords(&response);
+ Ok(keywords)
+ }
+ }
+}
+```
+
+Key resilience features:
+- **Graceful Degradation**: Falls back to traditional completion when structured extraction fails
+- **Rate Limiting**: Implements 1-second delays between batch operations
+- **Comprehensive Logging**: Detailed debug logging for troubleshooting
+- **Input Validation**: Validates inputs before processing
+
+### 4.2 Performance Considerations
+
+The implementation addresses performance through several mechanisms:
+
+1. **Batch Processing**: Efficient handling of multiple embedding requests
+2. **Caching Strategy**: While not explicitly implemented, the design supports future caching layers
+3. **Asynchronous Operations**: Fully async implementation for non-blocking operation
+4. **Resource Management**: Proper cleanup of resources and connections
+
+### 4.3 Security and Privacy
+
+The implementation includes security considerations:
+
+- **API Key Protection**: Keys are passed through secure configuration
+- **Input Sanitization**: Removes code blocks and potentially harmful content
+- **Data Minimization**: Only extracts necessary information
+- **Privacy Awareness**: Prompts emphasize not revealing model information
+
+## 5. Usage Examples
+
+### 5.1 Creating an LLM Client
+
+```rust
+let llm_client = create_llm_client(&llm_config, &embedding_config)?;
+```
+
+### 5.2 Extracting Information from Content
+
+```rust
+// Extract keywords
+let keywords = llm_client.extract_keywords("I love hiking in the mountains").await?;
+
+// Generate embeddings
+let embedding = llm_client.embed("memory content").await?;
+
+// Extract structured facts
+let facts = llm_client.extract_structured_facts(&prompt).await?;
+```
+
+### 5.3 Using in Memory Processing Workflow
+
+```rust
+// In memory creation process
+let embedding = llm_client.embed(&content).await?;
+let keywords = llm_client.extract_keywords(&content).await?;
+let entities = llm_client.extract_entities(&prompt).await?;
+```
+
+## 6. Best Practices and Recommendations
+
+### 6.1 Configuration Guidelines
+
+1. **Model Selection**: Use efficient models for high-volume operations
+2. **Temperature Settings**: Lower temperatures for more consistent extraction
+3. **Token Limits**: Set appropriate limits based on expected content length
+4. **Rate Limiting**: Configure according to your LLM provider's limits
+
+### 6.2 Performance Optimization
+
+1. **Batch Requests**: Group embedding requests when possible
+2. **Connection Pooling**: Reuse client instances across operations
+3. **Caching**: Implement caching for frequently accessed content
+4. **Monitoring**: Track API usage and costs
+
+### 6.3 Error Handling
+
+1. **Implement Retry Logic**: For transient failures
+2. **Monitor Health**: Regularly check service availability
+3. **Graceful Degradation**: Provide fallback behavior when LLM services are unavailable
+4. **Detailed Logging**: Capture sufficient context for debugging
+
+## 7. Future Enhancements
+
+Potential improvements to the LLM Integration Domain:
+
+1. **Multiple Provider Support**: Extend beyond OpenAI to include other LLM providers
+2. **Advanced Caching**: Implement intelligent caching of embeddings and extractions
+3. **Adaptive Prompting**: Dynamically adjust prompts based on content characteristics
+4. **Cost Optimization**: Implement strategies to minimize API costs
+5. **Enhanced Security**: Add encryption for sensitive content processing
+
+The LLM Integration Domain represents a sophisticated implementation of LLM-powered intelligence in a memory management system, providing the cognitive capabilities that enable advanced AI agent functionality.
\ No newline at end of file
diff --git a/litho.docs/4.Deep-Exploration/Memory Management Domain.md b/litho.docs/4.Deep-Exploration/Memory Management Domain.md
index 3fd5acd..ae2513f 100644
--- a/litho.docs/4.Deep-Exploration/Memory Management Domain.md
+++ b/litho.docs/4.Deep-Exploration/Memory Management Domain.md
@@ -1,260 +1,422 @@
-# Memory Management Domain Technical Implementation Documentation
+# Memory Management Domain Technical Documentation
-## 1. Overview and Architecture
+## 1. Overview
-The **Memory Management Domain** serves as the central orchestrator for all memory-related operations in the `cortex-mem` system, providing a comprehensive lifecycle management solution for AI agent memories. This domain implements a modular, service-oriented architecture with clear separation of concerns, enabling intelligent storage, retrieval, optimization, and analysis of persistent knowledge.
+The **Memory Management Domain** serves as the central orchestrator for all memory operations within the Cortex-Mem system, providing a comprehensive solution for AI agent memory persistence, retrieval, and optimization. This domain enables intelligent software agents to maintain context across interactions by managing structured knowledge through advanced processing pipelines that leverage large language models (LLMs) and vector-based storage.
-### Core Responsibilities
-- Orchestrate CRUD operations for memory entities
-- Manage advanced processing pipelines (extraction, classification, deduplication)
-- Coordinate LLM-driven decision making for memory updates
-- Provide semantic search capabilities with relevance ranking
-- Enable batch operations and transactional integrity
+At its core, the Memory Manager integrates multiple specialized components including vector storage, LLM services, fact extraction, importance evaluation, duplicate detection, and content classification. The architecture follows a dependency injection pattern where external services are provided at construction time, enabling flexible composition and testability while maintaining separation of concerns.
+
+### Key Characteristics
+- **Modular Design**: Clear separation between core logic and supporting processors
+- **LLM-Augmented Processing**: Intelligent metadata generation using language models
+- **Semantic Capabilities**: Vector-based similarity search with hybrid scoring
+- **Lifecycle Management**: Full CRUD operations with automated enhancement
+- **Optimization Ready**: Built-in support for deduplication and quality improvement
+
+## 2. Architecture Diagram
+
+```mermaid
+graph TD
+ A[External Services] --> B[MemoryManager]
+ B --> C[VectorStore]
+ B --> D[LLMClient]
+ B --> E[FactExtractor]
+ B --> F[MemoryUpdater]
+ B --> G[ImportanceEvaluator]
+ B --> H[DuplicateDetector]
+ B --> I[MemoryClassifier]
+ C --> J[(Persistent Storage)]
+ D --> K[Language Model API]
+ E --> L[Fact Extraction]
+ F --> M[Memory Update Logic]
+ G --> N[Importance Scoring]
+ H --> O[Deduplication]
+ I --> P[Content Classification]
+ B --> Q[Core Operations]
+ Q --> R[CRUD Operations]
+ Q --> S[Search & Retrieval]
+ Q --> T[Statistics & Health]
+```
+
+## 3. Core Components and Interfaces
+
+### 3.1 MemoryManager
+
+The `MemoryManager` struct is the primary entry point for all memory operations, coordinating interactions between various subsystems:
-### Architectural Pattern
-The domain follows a **composition pattern** where the `MemoryManager` class acts as the primary facade, integrating specialized components through dependency injection:
```rust
pub struct MemoryManager {
vector_store: Box,
llm_client: Box,
- fact_extractor: Box,
- memory_updater: Box,
- importance_evaluator: Box,
- duplicate_detector: Box,
- memory_classifier: Box
+ config: MemoryConfig,
+ fact_extractor: Box,
+ memory_updater: Box,
+ importance_evaluator: Box,
+ duplicate_detector: Box,
+ memory_classifier: Box,
}
```
-This design enables pluggable implementations while maintaining loose coupling between components.
+#### Construction Pattern
+The manager uses dependency injection to receive essential services:
+```rust
+impl MemoryManager {
+ pub fn new(
+ vector_store: Box,
+ llm_client: Box,
+ config: MemoryConfig,
+ ) -> Self { /* ... */ }
+}
+```
----
+This approach allows for flexible configuration and testing, with internal processors created from cloned references to the injected dependencies.
-## 2. Key Components and Their Interactions
+### 3.2 Key Interfaces
-### 2.1 MemoryManager - Central Orchestrator
+#### VectorStore Interface
+Provides persistent storage capabilities:
+- `insert(&self, memory: &Memory) -> Result<()>`: Store a memory record
+- `search(&self, query_vector: &[f32], filters: &Filters, limit: usize) -> Result>`: Semantic similarity search
+- `get(&self, id: &str) -> Result>`: Retrieve by ID
+- `update(&self, memory: &Memory) -> Result<()>`: Update existing record
+- `delete(&self, id: &str) -> Result<()>`: Remove from storage
+- `list(&self, filters: &Filters, limit: Option) -> Result>`: Filtered retrieval
+- `health_check(&self) -> Result`: Database connectivity check
-The `MemoryManager` (implemented in `cortex-mem-core/src/memory/manager.rs`) serves as the single entry point for all memory operations, coordinating interactions between various subsystems.
+#### LLMClient Interface
+Enables interaction with language model services:
+- `complete(&self, prompt: &str) -> Result`: Text generation
+- `embed(&self, text: &str) -> Result>`: Generate embeddings
+- `classify_memory(&self, prompt: &str) -> Result`: Content categorization
+- `extract_keywords(&self, content: &str) -> Result>`: Keyword extraction
+- `summarize(&self, content: &str, max_length: Option) -> Result`: Content summarization
+- `health_check(&self) -> Result`: Service availability check
-#### Primary Functions:
-- **Request Routing**: Directs incoming requests to appropriate handlers based on content type and operation
-- **Dependency Injection**: Manages instances of LLM clients, vector stores, extractors, and evaluators
-- **Transaction Coordination**: Ensures atomicity across multiple operations (create/update/delete)
+#### Specialized Processors
+| Processor | Purpose |
+|---------|--------|
+| **FactExtractor** | Extract structured facts from conversations |
+| **MemoryUpdater** | Determine optimal actions (CREATE/UPDATE/MERGE/DELETE) |
+| **ImportanceEvaluator** | Score memory value on 0-1 scale |
+| **DuplicateDetector** | Identify and merge redundant memories |
+| **MemoryClassifier** | Categorize content type and extract entities/topics |
-#### Critical Methods:
-| Method | Purpose | Implementation File |
-|-------|--------|-------------------|
-| `add_memory()` | Process conversation messages into structured facts | manager.rs |
-| `store()` | Store simple content with metadata enhancement | manager.rs |
-| `search_memories()` | Execute semantic searches with filtering | manager.rs |
-| `list()` | Retrieve memories with pagination and filters | manager.rs |
+## 4. Core Functionalities
-### 2.2 Interaction Flow
+### 4.1 Enhanced Memory Creation
-```mermaid
-sequenceDiagram
- participant Client
- participant Handler
- participant MemoryManager
- participant LLMClient
- participant VectorStore
-
- Client->>Handler: create_memory(request)
- activate Handler
- Handler->>MemoryManager: add_memory(messages, metadata)
- activate MemoryManager
-
- alt Simple Content
- MemoryManager->>LLMClient: embed(content)
- activate LLMClient
- LLMClient-->>MemoryManager: embedding
- deactivate LLMClient
- MemoryManager->>MemoryManager: generate_hash()
- MemoryManager->>VectorStore: insert(memory)
- else Conversation
- MemoryManager->>FactExtractor: extract_facts(messages)
- activate FactExtractor
- FactExtractor-->>MemoryManager: extracted_facts
- deactivate FactExtractor
-
- loop For each fact
- MemoryManager->>LLMClient: embed(fact.content)
- LLMClient-->>MemoryManager: embedding
- MemoryManager->>VectorStore: search(similar_memories)
- VectorStore-->>MemoryManager: results
- MemoryManager->>MemoryUpdater: update_memories()
- activate MemoryUpdater
- MemoryUpdater->>LLMClient: complete(prompt)
- LLMClient-->>MemoryUpdater: decisions
- MemoryUpdater-->>MemoryManager: UpdateResult
- deactivate MemoryUpdater
-
- alt CREATE
- MemoryManager->>MemoryManager: create_memory()
- MemoryManager->>VectorStore: insert()
- else UPDATE
- MemoryManager->>VectorStore: update()
- else MERGE
- MemoryManager->>MemoryManager: merge_memories()
- MemoryManager->>VectorStore: update/delete()
- end
- end
- end
-
- MemoryManager-->>Handler: MemoryResult[]
- deactivate MemoryManager
- Handler-->>Client: response
- deactivate Handler
-```
+The `enhance_memory` method adds rich metadata through LLM-powered analysis:
----
+```rust
+async fn enhance_memory(&self, memory: &mut Memory) -> Result<()> {
+ // Extract keywords
+ if let Ok(keywords) = self.llm_client.extract_keywords(&memory.content).await {
+ memory.metadata.custom.insert("keywords", serde_json::Value::Array(
+ keywords.into_iter().map(serde_json::Value::String).collect()
+ ));
+ }
-## 3. Advanced Processing Pipeline
+ // Generate summary for long content
+ if memory.content.len() > self.config.auto_summary_threshold {
+ if let Ok(summary) = self.llm_client.summarize(&memory.content, Some(200)).await {
+ memory.metadata.custom.insert("summary", serde_json::Value::String(summary));
+ }
+ }
-### 3.1 Fact Extraction System
+ // Classify memory type and extract metadata
+ if let Ok(memory_type) = self.memory_classifier.classify_memory(&memory.content).await {
+ memory.metadata.memory_type = memory_type;
+ }
-Implemented in `cortex-mem-core/src/memory/extractor.rs`, this component extracts meaningful information from conversational context using dual-channel analysis:
+ // Extract entities and topics
+ if let Ok(entities) = self.memory_classifier.extract_entities(&memory.content).await {
+ memory.metadata.entities = entities;
+ }
-#### Extraction Strategies:
-- **DualChannel**: Extract both user and assistant facts
-- **UserOnly**: Focus on user-provided information only
-- **AssistantOnly**: Capture assistant-generated insights
-- **ProceduralMemory**: Specialized for step-by-step processes
+ if let Ok(topics) = self.memory_classifier.extract_topics(&memory.content).await {
+ memory.metadata.topics = topics;
+ }
-#### Fact Structure:
-```rust
-pub struct ExtractedFact {
- pub content: String,
- pub importance: f32,
- pub category: FactCategory,
- pub entities: Vec,
- pub language: Option,
- pub source_role: String // "user" or "assistant"
-}
+ // Evaluate importance
+ if let Ok(importance) = self.importance_evaluator.evaluate_importance(memory).await {
+ memory.metadata.importance_score = importance;
+ }
-pub enum FactCategory {
- Personal, // Personal information about users
- Preference, // User preferences and likes/dislikes
- Factual, // General factual information
- Procedural, // How-to information and procedures
- Contextual, // Context about ongoing conversations
+ // Check for duplicates and merge if necessary
+ if let Ok(duplicates) = self.duplicate_detector.detect_duplicates(memory).await {
+ if !duplicates.is_empty() {
+ let mut all_memories = vec![memory.clone()];
+ all_memories.extend(duplicates);
+
+ if let Ok(merged_memory) = self.duplicate_detector.merge_memories(&all_memories).await {
+ *memory = merged_memory;
+
+ // Remove old duplicates
+ for duplicate in &all_memories[1..] {
+ let _ = self.vector_store.delete(&duplicate.id).await;
+ }
+ }
+ }
+ }
}
```
-#### Prompt Engineering:
-Uses carefully crafted prompts to prevent hallucinations and ensure fidelity:
-```text
-[IMPORTANT]: GENERATE FACTS SOLELY BASED ON THE USER'S MESSAGES.
-DO NOT INCLUDE INFORMATION FROM ASSISTANT OR SYSTEM MESSAGES.
-```
+Key features include:
+- Automatic keyword extraction and summarization
+- Content classification into six types: Conversational, Procedural, Factual, Semantic, Episodic, Personal
+- Entity and topic recognition
+- Importance scoring using hybrid rule-based and LLM approaches
+- Duplicate detection and automatic merging
-### 3.2 Memory Classification System
+### 4.2 Conversation-Based Memory Processing
-Located in `cortex-mem-core/src/memory/classification.rs`, this module categorizes memories into distinct types using hybrid approaches.
+The `add_memory` method handles conversation inputs through a sophisticated pipeline:
-#### Supported Types (`types.rs`):
```rust
-pub enum MemoryType {
- Conversational,
- Procedural,
- Factual,
- Semantic,
- Episodic,
- Personal,
-}
-```
+pub async fn add_memory(
+ &self,
+ messages: &[Message],
+ metadata: MemoryMetadata,
+) -> Result> {
+ // Handle procedural memory special case
+ if metadata.agent_id.is_some() && metadata.memory_type == MemoryType::Procedural {
+ return self.create_procedural_memory(messages, metadata).await;
+ }
-#### Classification Strategies:
-| Strategy | Use Case | Threshold |
-|---------|---------|-----------|
-| **LLM-based** | High accuracy classification | Default |
-| **Rule-based** | Fast processing | Content length < 100 chars |
-| **Hybrid** | Balance speed and accuracy | Configurable threshold |
+ // Primary fact extraction
+ let extracted_facts = self.fact_extractor.extract_facts(messages).await?;
+ let mut final_extracted_facts = extracted_facts;
-#### Keyword Matching (Multilingual Support):
-```rust
-// Chinese keywords
-"我喜欢", "我擅长", "我的名字叫", "我是", "我住在"
+ // Fallback strategies
+ if final_extracted_facts.is_empty() {
+ // Try user-focused extraction
+ let user_messages: Vec<_> = messages.iter().filter(|msg| msg.role == "user").cloned().collect();
+
+ if !user_messages.is_empty() {
+ if let Ok(user_facts) = self.fact_extractor.extract_user_facts(&user_messages).await {
+ if !user_facts.is_empty() {
+ final_extracted_facts = user_facts;
+ }
+ }
+ }
-// English keywords
-"i like", "my name", "i live", "i prefer", "i work"
-```
+ // Individual message extraction
+ if final_extracted_facts.is_empty() {
+ let mut single_message_facts = Vec::new();
+ for message in messages {
+ if let Ok(mut facts) = self.fact_extractor.extract_facts_from_text(&message.content).await {
+ for fact in &mut facts {
+ fact.source_role = message.role.clone();
+ }
+ single_message_facts.extend(facts);
+ }
+ }
+ if !single_message_facts.is_empty() {
+ final_extracted_facts = single_message_facts;
+ }
+ }
-### 3.3 Importance Evaluation Framework
+ // Ultimate fallback - store raw user content
+ if final_extracted_facts.is_empty() {
+ let user_content = messages
+ .iter()
+ .filter(|msg| msg.role == "user")
+ .map(|msg| format!("用户: {}", msg.content))
+ .collect::>()
+ .join("\n");
+
+ if !user_content.trim().is_empty() {
+ let memory_id = self.store(user_content.clone(), metadata).await?;
+ return Ok(vec![/* ... */]);
+ }
+ }
+ }
+
+ // Process each fact through update pipeline
+ for fact in &final_extracted_facts {
+ let query_embedding = self.llm_client.embed(&fact.content).await?;
+ let existing_memories = self.vector_store.search_with_threshold(
+ &query_embedding,
+ &filters,
+ 5,
+ self.config.search_similarity_threshold,
+ ).await?;
+
+ let update_result = self.memory_updater.update_memories(
+ &[fact.clone()],
+ &existing_memories,
+ &metadata
+ ).await?;
+
+ // Apply resulting actions
+ for action in &update_result.actions_performed {
+ match action {
+ MemoryAction::Create { content, metadata } => {
+ let memory_id = self.store(content.clone(), metadata.clone()).await?;
+ // Record result
+ }
+ MemoryAction::Update { id, content } => {
+ self.update(id, content.clone()).await?;
+ // Record result
+ }
+ MemoryAction::Merge { target_id, source_ids, merged_content } => {
+ self.update(target_id, merged_content.clone()).await?;
+ for source_id in source_ids {
+ self.vector_store.delete(source_id).await?;
+ }
+ // Record result
+ }
+ MemoryAction::Delete { id } => {
+ self.vector_store.delete(id).await?;
+ // Record result
+ }
+ }
+ }
+ }
+}
+```
-Defined in `cortex-mem-core/src/memory/importance.rs`, this system scores memories on a 0-1 scale using three-tiered approach.
+Processing includes multiple fallback strategies:
+1. Primary fact extraction using dual-channel analysis
+2. User-focused extraction as first fallback
+3. Individual message processing as second fallback
+4. Raw user content storage as ultimate fallback
-#### Scoring Criteria:
-| Score Range | Category | Characteristics |
-|-----------|---------|----------------|
-| 0.0-0.2 | Trivial | Small talk, temporary states |
-| 0.2-0.4 | Low | Minor preferences, casual mentions |
-| 0.4-0.6 | Medium | Useful context, moderate preferences |
-| 0.6-0.8 | High | Key facts, strong preferences |
-| 0.8-1.0 | Critical | Core identity, essential information |
+### 4.3 Search Optimization
-#### Evaluation Factors:
-- Content length
-- Memory type weighting
-- Presence of important keywords
-- Contextual significance
-- Emotional indicators
+The search functionality combines semantic similarity with importance weighting:
-#### Hybrid Approach:
```rust
-fn evaluate_importance(&self, memory: &Memory) -> Result {
- let rule_score = self.evaluate_by_content_length(&memory.content);
- let keyword_bonus = self.evaluate_by_keywords(&memory.content);
- let type_weight = self.evaluate_by_memory_type(&memory.metadata.memory_type);
+// In implementation...
+async fn search_with_threshold(
+ &self,
+ query: &str,
+ filters: &Filters,
+ limit: usize,
+ threshold: f32
+) -> Result> {
+ let query_embedding = self.llm_client.embed(query).await?;
+ let similar_memories = self.vector_store.search(&query_embedding, filters, limit).await?;
- // Only use LLM evaluation for potentially important memories
- if (rule_score + keyword_bonus + type_weight) > 0.5 && self.auto_enhance {
- return self.llm_evaluation(memory).await;
+ // Apply threshold filtering
+ let filtered_memories: Vec = similar_memories
+ .into_iter()
+ .filter(|scored_memory| scored_memory.score >= threshold)
+ .collect();
+
+ // Enhance with importance scores
+ let mut enhanced_results = Vec::new();
+ for mut scored_memory in filtered_memories {
+ let combined_score = self.combine_scores(
+ scored_memory.score,
+ scored_memory.memory.metadata.importance_score
+ );
+ scored_memory.score = combined_score;
+ enhanced_results.push(scored_memory);
}
-
- (rule_score + keyword_bonus + type_weight).min(1.0)
+
+ // Sort by combined score
+ enhanced_results.sort_by(|a, b| b.score.partial_cmp(&a.score).unwrap());
+ Ok(enhanced_results)
}
```
-### 3.4 Update Strategy Engine
+Search features:
+- Configurable similarity thresholds
+- Hybrid scoring combining embedding similarity and importance
+- Metadata filtering capabilities
+- Ranked results presentation
+
+### 4.4 Procedural Memory Support
-Implemented in `cortex-mem-core/src/memory/updater.rs`, this component makes intelligent decisions about how to handle new information.
+Special handling exists for procedural memories that preserve action-result sequences:
-#### Action Hierarchy:
```rust
-pub enum MemoryAction {
- Ignore { reason: String }, // > Priority
- Merge { target_id: String }, //
- Update { id: String }, //
- Create {}, // Lowest priority
+async fn create_procedural_memory(
+ &self,
+ messages: &[Message],
+ metadata: MemoryMetadata
+) -> Result> {
+ // Use specialized system prompt for procedural memory
+ let prompt = format!(
+ "{}\n\n{}",
+ PROCEDURAL_MEMORY_SYSTEM_PROMPT,
+ parse_messages(messages)
+ );
+
+ // Extract procedural facts
+ let procedural_facts = self.fact_extractor.extract_facts_filtered(
+ messages,
+ &["user", "assistant"]
+ ).await?;
+
+ // Create sequential memory entries
+ let mut results = Vec::new();
+ for (i, fact) in procedural_facts.iter().enumerate() {
+ let mut fact_metadata = metadata.clone();
+ fact_metadata.custom.insert(
+ "sequence_position".to_string(),
+ serde_json::Value::Number(i.into())
+ );
+
+ let memory_id = self.store(fact.content.clone(), fact_metadata).await?;
+ results.push(/* ... */);
+ }
+
+ Ok(results)
}
```
-#### Decision Logic:
-```text
-PREFERENCE HIERARCHY:
-- Prefer IGNORE over UPDATE/MERGE to prevent duplication
-- Use MERGE for related but redundant facts
-- Only CREATE when information is truly unique
-- Consider information density: consolidate small related facts
-```
+### 4.5 Comprehensive Statistics
-#### LLM Prompt Design:
-```text
-For each fact, decide one of:
-3. IGNORE - Redundant or already covered
-2. MERGE - Related/complementary information
-1. UPDATE - Adds genuinely new substantial information
-0. CREATE - Completely novel and valuable
-```
+Detailed analytics are available through the `get_stats` method:
----
+```rust
+pub async fn get_stats(&self) -> Result {
+ let all_memories = self.vector_store.list(&Filters::default(), None).await?;
+
+ let stats = MemoryStats {
+ total_count: all_memories.len(),
+ by_type: all_memories.iter().fold(HashMap::new(), |mut acc, mem| {
+ *acc.entry(format!("{:?}", mem.metadata.memory_type)).or_insert(0) += 1;
+ acc
+ }),
+ by_user: all_memories.iter().fold(HashMap::new(), |mut acc, mem| {
+ if let Some(ref user_id) = mem.metadata.user_id {
+ *acc.entry(user_id.clone()).or_insert(0) += 1;
+ }
+ acc
+ }),
+ by_agent: all_memories.iter().fold(HashMap::new(), |mut acc, mem| {
+ if let Some(ref agent_id) = mem.metadata.agent_id {
+ *acc.entry(agent_id.clone()).or_insert(0) += 1;
+ }
+ acc
+ }),
+ average_importance: all_memories.iter()
+ .map(|m| m.metadata.importance_score)
+ .sum::() / all_memories.len() as f32,
+ date_range: if !all_memories.is_empty() {
+ let mut timestamps: Vec<_> = all_memories.iter()
+ .map(|m| m.created_at.timestamp())
+ .collect();
+ timestamps.sort();
+ Some((timestamps[0], timestamps[timestamps.len()-1]))
+ } else {
+ None
+ },
+ };
+
+ Ok(stats)
+}
+```
-## 4. Data Model and Storage
+## 5. Data Structures
-### 4.1 Core Data Structures (`types.rs`)
+### 5.1 Memory Structure
-#### Memory Entity:
```rust
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct Memory {
pub id: String,
pub content: String,
@@ -265,8 +427,10 @@ pub struct Memory {
}
```
-#### Metadata Schema:
+### 5.2 Memory Metadata
+
```rust
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct MemoryMetadata {
pub user_id: Option,
pub agent_id: Option,
@@ -282,285 +446,285 @@ pub struct MemoryMetadata {
}
```
-#### Search Filters:
+### 5.3 Memory Types
+
+```rust
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
+pub enum MemoryType {
+ Conversational,
+ Procedural,
+ Factual,
+ Semantic,
+ Episodic,
+ Personal,
+}
+```
+
+### 5.4 Search Filters
+
```rust
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct Filters {
pub user_id: Option,
pub agent_id: Option,
pub run_id: Option,
+ pub actor_id: Option,
+ pub memory_type: Option,
pub min_importance: Option,
pub max_importance: Option,
pub created_after: Option>,
+ pub created_before: Option>,
+ pub updated_after: Option>,
+ pub updated_before: Option>,
pub entities: Option>,
pub topics: Option>,
pub custom: HashMap,
}
```
-### 4.2 Vector Store Integration
-
-The Qdrant integration (`qdrant.rs`) provides persistent storage with semantic search capabilities.
+## 6. Implementation Details
-#### Collection Management:
-- Auto-detection of embedding dimensions
-- Schema validation and migration
-- Index optimization for high-dimensional vectors
+### 6.1 Dependency Injection Pattern
-#### Query Operations:
-- Exact match via UUID
-- Semantic similarity search
-- Filtered queries by metadata fields
-- Batch operations support
+The system employs a clean dependency injection pattern where the `MemoryManager` receives external services at construction time and creates specialized processors:
-#### Embedding Generation:
```rust
-async fn embed(&self, text: &str) -> Result> {
- let builder = EmbeddingsBuilder::new(self.embedding_model.clone())
- .document(text)
- .map_err(|e| MemoryError::LLM(e.to_string()))?;
-
- let embeddings = builder.build().await.map_err(|e| MemoryError::LLM(e.to_string()))?;
-
- Ok(embeddings.first().unwrap().1.vec.iter().map(|&x| x as f32).collect())
+impl MemoryManager {
+ pub fn new(
+ vector_store: Box,
+ llm_client: Box,
+ config: MemoryConfig,
+ ) -> Self {
+ let fact_extractor = create_fact_extractor(dyn_clone::clone_box(llm_client.as_ref()));
+ let memory_updater = create_memory_updater(
+ dyn_clone::clone_box(llm_client.as_ref()),
+ dyn_clone::clone_box(vector_store.as_ref()),
+ config.similarity_threshold,
+ config.merge_threshold,
+ );
+ let importance_evaluator = create_importance_evaluator(
+ dyn_clone::clone_box(llm_client.as_ref()),
+ config.auto_enhance,
+ Some(0.5),
+ );
+ let duplicate_detector = create_duplicate_detector(
+ dyn_clone::clone_box(vector_store.as_ref()),
+ dyn_clone::clone_box(llm_client.as_ref()),
+ config.auto_enhance,
+ config.similarity_threshold,
+ config.merge_threshold,
+ );
+ let memory_classifier = create_memory_classifier(
+ dyn_clone::clone_box(llm_client.as_ref()),
+ config.auto_enhance,
+ Some(100),
+ );
+
+ Self {
+ vector_store,
+ llm_client,
+ config,
+ fact_extractor,
+ memory_updater,
+ importance_evaluator,
+ duplicate_detector,
+ memory_classifier,
+ }
+ }
}
```
----
-
-## 5. Operational Workflows
+### 6.2 Factory Functions
-### 5.1 Memory Creation Workflow
+Processor creation is handled through factory functions that select appropriate implementations based on configuration:
-```mermaid
-graph TD
- A[External Request] --> B{Request Type}
- B -->|CRUD Operation| C[MemoryManager]
- B -->|Search| D[MemoryManager]
- B -->|Batch Operation| E[MemoryManager]
-
- C --> F[Extract Parameters]
- C --> G[Validate Input]
-
- F --> H{Content Type}
- H -->|Simple| I[Create Direct Memory]
- H -->|Conversation| J[Extract Facts]
-
- J --> K[Find Similar Memories]
- K --> L[MemoryUpdater Decision]
- L --> M{Action}
- M -->|CREATE| N[Create New Memory]
- M -->|UPDATE| O[Update Existing Memory]
- M -->|MERGE| P[Merge Memories]
- M -->|IGNORE| Q[Skip Storage]
-
- I --> R[Generate Embedding]
- N --> R
- O --> R
- P --> R
-
- R --> S[Enhance Metadata]
- S --> T[Store in VectorDB]
-```
-
-### 5.2 Search Workflow
-
-```mermaid
-flowchart TD
- A[User/Application] --> B{Initiate Search}
- B --> C[Send Search Request with Query]
- C --> D[Generate Query Embedding via LLM]
- D --> E[Semantic Search in Qdrant DB]
- E --> F[Apply Metadata Filters]
- F --> G[Rank by Similarity + Importance]
- G --> H[Return Ranked Matching Memories]
- H --> A
-```
-
-#### Ranking Algorithm:
-```python
-final_score = (similarity_score * 0.7) + (importance_score * 0.3)
+```rust
+// Example from importance.rs
+pub fn create_importance_evaluator(
+ llm_client: Box,
+ use_llm: bool,
+ hybrid_threshold: Option,
+) -> Box {
+ match (use_llm, hybrid_threshold) {
+ (true, Some(threshold)) => Box::new(HybridImportanceEvaluator::new(llm_client, threshold)),
+ (true, None) => Box::new(LLMImportanceEvaluator::new(llm_client)),
+ (false, _) => Box::new(RuleBasedImportanceEvaluator::new()),
+ }
+}
```
-Configurable weights allow tuning precision vs. relevance trade-offs.
-
----
-
-## 6. Configuration and Extensibility
+Similar patterns exist for other processors, allowing runtime selection between LLM-enhanced and rule-based approaches.
-### 6.1 Configuration Model
+### 6.3 Error Handling Strategy
-Centralized configuration via TOML files supports:
-- Server settings (host, port)
-- Qdrant connection parameters
-- LLM provider configuration
-- Memory behavior tuning (thresholds, timeouts)
-- Optimization strategies
+The system implements comprehensive error handling throughout:
-Key configuration files identified:
-- `config.toml` (main configuration)
-- `examples/cortex-mem-evaluation/config/*.toml` (evaluation configurations)
-
-### 6.2 Extension Points
-
-#### Pluggable Components:
-1. **New Vector Stores**: Implement `VectorStore` trait
-2. **Additional LLM Providers**: Implement `LLMClient` trait
-3. **Custom Detectors**: Extend optimization detection logic
-4. **New Interfaces**: Add gRPC, WebSocket, or other protocols
-
-#### Trait-Based Design:
```rust
-#[async_trait]
-pub trait MemoryUpdater: Send + Sync {
- async fn update_memories(
- &self,
- facts: &[ExtractedFact],
- existing_memories: &[ScoredMemory],
- metadata: &MemoryMetadata,
- ) -> Result;
+pub async fn create_memory(&self, content: String, metadata: MemoryMetadata) -> Result {
+ if content.trim().is_empty() {
+ return Err(MemoryError::Validation(
+ "Content cannot be empty when creating memory".to_string(),
+ ));
+ }
+
+ // ... rest of implementation
}
```
-This enables runtime swapping of implementations based on configuration.
+Error types include:
+- `MemoryError::Validation` - Input validation failures
+- `MemoryError::Storage` - Persistent storage issues
+- `MemoryError::LLM` - Language model service errors
+- `MemoryError::Parse` - Data parsing/formatting errors
+- `MemoryError::NotFound` - Resource not found
----
+## 7. Sequence Diagrams
-## 7. Quality Assurance and Reliability Features
+### 7.1 Memory Addition Flow
-### 7.1 Deduplication System
-
-The `deduplication.rs` module prevents information redundancy through:
-
-#### Detection Methods:
-- **Hash Matching**: SHA-256 comparison for exact duplicates
-- **Semantic Similarity**: Cosine similarity on embeddings (>0.8 threshold)
-- **Content Overlap**: Jaccard index for word overlap
-- **Metadata Alignment**: Entity/topic matching
-
-#### Merging Logic:
-```rust
-async fn merge_memories(&self, memories: &[Memory]) -> Result {
- let prompt = self.create_merge_prompt(memories);
- let merged_content = self.llm_client.complete(&prompt).await?;
+```mermaid
+sequenceDiagram
+ participant Client
+ participant MemoryManager
+ participant VectorStore
+ participant LLMClient
+ participant FactExtractor
+ participant MemoryUpdater
+ participant DuplicateDetector
+ participant MemoryClassifier
+ participant ImportanceEvaluator
- // Preserve highest importance score
- let importance_score = memories.iter()
- .map(|m| m.metadata.importance_score)
- .max_by(|a,b| a.partial_cmp(b).unwrap())
- .unwrap_or(0.5);
-
- Ok(Memory::new(merged_content, embedding, metadata))
-}
+ Client->>MemoryManager: add_memory(messages, metadata)
+ MemoryManager->>FactExtractor: extract_facts(messages)
+ alt No facts extracted
+ MemoryManager->>FactExtractor: extract_user_facts(user_messages)
+ end
+ MemoryManager->>VectorStore: search(existing_memories)
+ MemoryManager->>MemoryUpdater: update_memories(facts, existing_memories, metadata)
+ loop For each action
+ alt Action == CREATE
+ MemoryManager->>MemoryManager: create_memory(content, metadata)
+ MemoryManager->>MemoryClassifier: classify_memory(content)
+ MemoryManager->>ImportanceEvaluator: evaluate_importance(memory)
+ MemoryManager->>DuplicateDetector: detect_duplicates(memory)
+ alt Has duplicates
+ MemoryManager->>DuplicateDetector: merge_memories(all_memories)
+ MemoryManager->>VectorStore: insert(merged_memory)
+ MemoryManager->>VectorStore: delete(duplicate_ids)
+ else No duplicates
+ MemoryManager->>VectorStore: insert(new_memory)
+ end
+ else Action == UPDATE
+ MemoryManager->>VectorStore: update(updated_memory)
+ else Action == MERGE
+ MemoryManager->>DuplicateDetector: merge_memories(memories)
+ MemoryManager->>VectorStore: update(merged_memory)
+ MemoryManager->>VectorStore: delete(source_ids)
+ else Action == DELETE
+ MemoryManager->>VectorStore: delete(memory_id)
+ end
+ end
+ MemoryManager->>Client: return actions_performed
+
+ Client->>MemoryManager: store(content, metadata)
+ MemoryManager->>DuplicateDetector: detect_duplicates(content)
+ alt Is duplicate
+ MemoryManager-->>Client: return existing_id
+ else Not duplicate
+ MemoryManager->>MemoryManager: create_memory(content, metadata)
+ MemoryManager->>VectorStore: insert(memory)
+ MemoryManager-->>Client: return new_id
+ end
+
+ Client->>MemoryManager: search(query, filters)
+ MemoryManager->>LLMClient: embed(query)
+ MemoryManager->>VectorStore: search(query_vector, filters)
+ MemoryManager->>ImportanceEvaluator: evaluate_importance(memory)
+ MemoryManager->>MemoryManager: combine_scores(similarity, importance)
+ MemoryManager->>MemoryManager: sort_results(combined_scores)
+ MemoryManager-->>Client: return scored_memories
```
-### 7.2 Error Handling and Recovery
+## 8. Configuration Options
-Robust error handling includes:
-- Graceful degradation when LLM services are unavailable
-- Retry mechanisms for transient failures
-- Comprehensive logging via `tracing` crate
-- Health checks for dependent services
+The system supports extensive configuration through `MemoryConfig`:
-#### Health Check Endpoint:
```rust
-pub async fn health_check() -> HealthStatus {
- HealthStatus {
- overall: vector_store_healthy && llm_service_healthy,
- vector_store: vector_store_status,
- llm_service: llm_status,
- }
+pub struct MemoryConfig {
+ pub auto_enhance: bool,
+ pub auto_summary_threshold: usize,
+ pub similarity_threshold: f32,
+ pub merge_threshold: f32,
+ pub search_similarity_threshold: f32,
+ // Additional configuration fields...
}
```
----
-
-## 8. Practical Usage Examples
+Key parameters:
+- `auto_enhance`: Enable/disable LLM-powered metadata enhancement
+- `auto_summary_threshold`: Minimum content length for automatic summarization
+- `similarity_threshold`: Base threshold for determining memory similarity
+- `merge_threshold`: Threshold for automatic memory merging
+- `search_similarity_threshold`: Minimum similarity for search results
-### 8.1 Creating a Memory via API
+## 9. Best Practices and Recommendations
-**HTTP Request:**
-```http
-POST /memories
-Content-Type: application/json
+### 9.1 Usage Patterns
-{
- "content": "I'm a software engineer who loves Rust programming",
- "user_id": "user_123",
- "memory_type": "personal"
-}
+#### Direct Memory Storage
+For simple content storage without conversation analysis:
+```rust
+let memory_id = memory_manager.store("User prefers dark mode interface".to_string(), metadata).await?;
```
-**Processing Steps:**
-1. Hash generated: `SHA-256("I'm a software engineer...")`
-2. Embedding created via LLM
-3. Classification: Detected as "Personal" type
-4. Entities extracted: ["software engineer", "Rust"]
-5. Importance scored: 0.75 (high due to personal preference)
-6. Stored in Qdrant with full metadata
-
-### 8.2 Searching Memories
-
-**Query:**
-```http
-POST /memories/search
-{
- "query": "What do I like?",
- "filters": {
- "user_id": "user_123",
- "min_importance": 0.5
- }
-}
-```
+#### Conversation Processing
+For extracting meaningful information from dialogues:
+```rust
+let messages = vec![
+ Message { role: "user".to_string(), content: "I really like hiking in the mountains".to_string(), name: None },
+ Message { role: "assistant".to_string(), content: "That sounds like a great outdoor activity!".to_string(), name: None },
+];
-**Response:**
-```json
-{
- "results": [
- {
- "memory": {
- "id": "mem_abc",
- "content": "I love Rust programming",
- "metadata": {
- "importance_score": 0.75,
- "entities": ["Rust"]
- }
- },
- "score": 0.92
- }
- ]
-}
+let results = memory_manager.add_memory(&messages, metadata).await?;
```
----
-
-## 9. Recommendations for Enhancement
+#### Semantic Search
+For finding relevant memories:
+```rust
+let filters = Filters {
+ user_id: Some("user123".to_string()),
+ min_importance: Some(0.5),
+ ..Default::default()
+};
-While the current implementation demonstrates strong architectural foundations, several improvements could enhance its capabilities:
+let results = memory_manager.search("outdoor activities", &filters, 5).await?;
+```
-### 9.1 Immediate Improvements
-1. **Add Caching Layer**: Implement Redis cache for frequently accessed memories to reduce LLM/vector DB load
-2. **Streaming APIs**: Introduce streaming responses for large result sets and long-running optimizations
-3. **Authentication Framework**: Add JWT-based authentication and authorization controls
-4. **Enhanced Monitoring**: Integrate Prometheus metrics and OpenTelemetry tracing
+### 9.2 Performance Considerations
-### 9.2 Long-Term Enhancements
-1. **Cross-Memory Reasoning**: Enable inference across multiple memories to derive new insights
-2. **Temporal Decay Model**: Implement automatic importance decay over time unless reinforced
-3. **Collaborative Filtering**: Allow sharing of anonymized patterns across users for improved recommendations
-4. **Multi-modal Support**: Extend to handle image, audio, and video content types
+1. **Batch Operations**: Process multiple facts together when possible
+2. **Filter Early**: Use metadata filters to reduce search scope
+3. **Threshold Tuning**: Adjust similarity thresholds based on use case requirements
+4. **Caching**: Consider caching frequent queries or expensive LLM operations
+5. **Asynchronous Processing**: Use async methods to avoid blocking
-### 9.3 Testing and Validation
-1. **Comprehensive Test Suite**: Develop unit and integration tests covering edge cases
-2. **Synthetic Dataset Generator**: Create tools for generating realistic test data
-3. **Performance Benchmarking**: Establish baseline performance metrics under varying loads
-4. **Security Auditing**: Conduct regular security reviews and penetration testing
+### 9.3 Integration Guidelines
----
+1. **Error Handling**: Always handle potential `Result` returns appropriately
+2. **Resource Management**: Ensure proper cleanup of connections and resources
+3. **Configuration Validation**: Validate configuration settings before initialization
+4. **Monitoring**: Implement logging and monitoring for critical operations
+5. **Testing**: Use mock implementations for unit testing
-## Conclusion
+## 10. Conclusion
-The Memory Management Domain in `cortex-mem` represents a sophisticated, production-ready implementation of AI agent memory systems. Its modular architecture combines cutting-edge technologies—vector databases, large language models, and intelligent automation—to deliver reliable, scalable memory management capabilities.
+The Memory Management Domain provides a robust foundation for AI agent memory systems, combining traditional CRUD operations with advanced LLM-powered intelligence. Its modular architecture enables both direct memory manipulation and sophisticated conversation-based knowledge extraction, making it suitable for complex agent workflows.
-By leveraging LLM-powered metadata enrichment, smart deduplication, and importance-aware retrieval, the system effectively balances automation with control, making it suitable for both research experimentation and enterprise deployment scenarios. The well-defined interfaces and extensible design ensure adaptability to evolving requirements while maintaining high cohesion within the domain.
+Key strengths include:
+- **Intelligent Enhancement**: Automatic metadata generation improves searchability
+- **Quality Control**: Built-in deduplication maintains memory collection integrity
+- **Flexible Access**: Multiple interfaces accommodate different use cases
+- **Extensible Design**: Clean abstractions allow for future enhancements
+- **Production Ready**: Comprehensive error handling and monitoring capabilities
-With continued investment in reliability features, monitoring, and security controls, this foundation can support increasingly complex AI applications requiring robust long-term contextual awareness.
\ No newline at end of file
+The implementation demonstrates best practices in Rust development, leveraging traits for abstraction, async/await for concurrency, and proper error handling throughout. By following the documented patterns and recommendations, developers can effectively integrate this memory management system into their AI applications.
\ No newline at end of file
diff --git a/litho.docs/4.Deep-Exploration/Memory Optimization Domain.md b/litho.docs/4.Deep-Exploration/Memory Optimization Domain.md
new file mode 100644
index 0000000..dc1dbc1
--- /dev/null
+++ b/litho.docs/4.Deep-Exploration/Memory Optimization Domain.md
@@ -0,0 +1,280 @@
+# Memory Optimization Domain Technical Documentation
+
+**Generation Time**: 2024-12-15 09:36:16 UTC
+**System Version**: cortex-mem v1.0.0
+
+## 1. Overview
+
+The **Memory Optimization Domain** is a core component of the Cortex-Mem system responsible for maintaining memory quality, efficiency, and relevance through systematic analysis and improvement processes. This domain enables AI agents to maintain high-quality contextual memory by identifying and resolving issues such as duplicates, low-quality entries, outdated information, and inefficient storage patterns.
+
+The optimization engine follows a comprehensive four-phase process (Detection → Analysis → Execution → Reporting) with progressive status updates from 0% to 100%. It supports both actual execution and dry-run preview modes, ensuring safe operation while providing detailed insights into potential improvements.
+
+## 2. Architecture Components
+
+### 2.1 Core Components
+
+#### 2.1.1 DefaultMemoryOptimizer
+The central coordinator implementing the `MemoryOptimizer` trait, responsible for managing the complete optimization workflow:
+
+```rust
+pub struct DefaultMemoryOptimizer {
+ memory_manager: Arc,
+ config: OptimizationConfig,
+ detector: Arc,
+ analyzer: Arc,
+ executor: Arc,
+ reporter: Arc,
+ running_optimizations: tokio::sync::RwLock>,
+}
+```
+
+This component orchestrates interactions between specialized sub-components using async/await patterns and maintains concurrent optimization task tracking via `RwLock>`.
+
+#### 2.1.2 OptimizationDetector
+Responsible for identifying memory issues based on configurable thresholds:
+- **Duplicate detection**: Uses vector similarity threshold (default: 0.85)
+- **Quality assessment**: Identifies low-quality memories (threshold: 0.4)
+- **Time decay analysis**: Flags potentially outdated entries (>180 days)
+- **Classification issues**: Detects poorly categorized memories
+
+#### 2.1.3 OptimizationAnalyzer
+Analyzes detected issues and formulates optimization strategies:
+- Evaluates issue severity (Low/Medium/High)
+- Generates actionable recommendations
+- Creates comprehensive optimization plans
+- Supports conservative mode for risk-averse operations
+
+#### 2.1.4 ExecutionEngine
+Executes optimization actions with robust error handling:
+- Batch processing support (configurable batch size)
+- Concurrent task execution (max_concurrent_tasks: 4)
+- Retry mechanism (up to 3 attempts)
+- Transactional integrity for memory operations
+
+#### 2.1.5 ResultReporter
+Generates detailed reports and metrics:
+- Comprehensive logging with tracing integration
+- Performance metrics collection
+- Structured result formatting
+- Optional file-based logging
+
+## 3. Key Data Structures
+
+### 3.1 OptimizationRequest
+Defines parameters for optimization operations:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `optimization_id` | Option | Unique identifier for tracking |
+| `strategy` | OptimizationStrategy | Selected optimization approach |
+| `filters` | OptimizationFilters | Scope constraints |
+| `aggressive` | bool | Risk tolerance level |
+| `dry_run` | bool | Preview mode flag |
+| `timeout_minutes` | Option | Execution time limit |
+
+### 3.2 OptimizationStrategy
+Enumeration of available optimization approaches:
+
+```rust
+enum OptimizationStrategy {
+ Full, // Comprehensive optimization
+ Incremental, // Recent changes only
+ Deduplication, // Focus on duplicate removal
+ Relevance, // Improve relevance scoring
+ Quality, // Enhance content quality
+ Space, // Optimize storage efficiency
+}
+```
+
+### 3.3 OptimizationPlan
+Structured representation of proposed optimizations:
+
+| Field | Description |
+|-------|-------------|
+| `optimization_id` | Unique plan identifier |
+| `strategy` | Applied optimization strategy |
+| `created_at` | Timestamp of plan creation |
+| `estimated_duration_minutes` | Predicted execution time |
+| `issues` | Detected problems list |
+| `actions` | Recommended operations |
+| `filters` | Applied scope filters |
+
+### 3.4 OptimizationAction
+Available action types in optimization plans:
+
+- `Merge`: Combine related memories
+- `Delete`: Remove redundant entries
+- `Update`: Modify existing memory
+- `Reclassify`: Change memory type
+- `Archive`: Move to archive storage
+
+## 4. Workflow Process
+
+### 4.1 Sequence Diagram
+```mermaid
+sequenceDiagram
+ participant UI as Optimization UI
+ participant Store as OptimizationStore
+ participant Optimizer as MemoryOptimizer
+ participant Detector as OptimizationDetector
+ participant Analyzer as OptimizationAnalyzer
+ participant Executor as ExecutionEngine
+ participant Reporter as ResultReporter
+
+ UI->>Store: runOptimization()
+ Store->>Optimizer: optimize(request)
+
+ Optimizer->>Optimizer: Initialize status
+ Optimizer->>Detector: detect_issues(filters)
+ Detector-->>Optimizer: issues[]
+
+ Optimizer->>Analyzer: create_optimization_plan(issues, strategy)
+ Analyzer-->>Optimizer: OptimizationPlan
+
+ alt Dry Run
+ Optimizer->>Optimizer: create_dry_run_result()
+ else Actual Execution
+ Optimizer->>Executor: execute_plan(plan)
+ Executor-->>Optimizer: OptimizationResult
+ end
+
+ Optimizer->>Reporter: report_optimization_result(result)
+ Reporter-->>Optimizer: success
+ Optimizer-->>Store: result
+ Store-->>UI: Update UI
+```
+
+### 4.2 Flowchart
+```mermaid
+graph TD
+ A[Start Optimization] --> B{Dry Run?}
+ B -->|Yes| C[Create Dry Run Result]
+ B -->|No| D[Execute Plan]
+ C --> E[Report Result]
+ D --> E
+ E --> F[Update Status]
+ F --> G[Complete]
+
+ subgraph Phases
+ H[Detection - 20%]
+ I[Analysis - 40%]
+ J[Execution - 80%]
+ K[Reporting - 100%]
+ end
+
+ A --> H --> I --> J --> K --> G
+```
+
+## 5. Implementation Details
+
+### 5.1 Trait-Based Architecture
+The system implements a clean separation of concerns through Rust traits:
+
+```rust
+#[async_trait]
+pub trait MemoryOptimizer: Send + Sync {
+ async fn optimize(&self, request: &OptimizationRequest) -> Result;
+ async fn create_optimization_plan(&self, strategy: OptimizationStrategy) -> Result;
+ async fn get_optimization_status(&self) -> Result>;
+ async fn cancel_optimization(&self, optimization_id: &str) -> Result<()>;
+}
+```
+
+### 5.2 Configuration Management
+Components use builder patterns with default configurations:
+
+```rust
+// Example configuration structure
+struct OptimizationDetectorConfig {
+ duplicate_threshold: f32, // Default: 0.85
+ quality_threshold: f32, // Default: 0.4
+ time_decay_days: u32, // Default: 180
+ max_issues_per_type: usize, // Default: 1000
+}
+```
+
+### 5.3 Error Handling and Logging
+Comprehensive error handling with structured logging:
+
+- Custom `Result` types for domain-specific errors
+- Tracing integration for detailed diagnostics
+- Graceful degradation for partial failures
+- Detailed error messages in results
+
+### 5.4 Concurrency Model
+Thread-safe design using Arc-wrapped components:
+
+```rust
+running_optimizations: tokio::sync::RwLock>
+```
+
+Supports multiple concurrent optimization jobs with proper synchronization.
+
+## 6. Integration Points
+
+### 6.1 Internal Dependencies
+- **MemoryManager**: Primary interface for memory CRUD operations
+- **LLM Integration**: For semantic analysis and similarity assessment
+- **Vector Store**: Access to embedding data for duplicate detection
+
+### 6.2 External Interfaces
+- **CLI Interface**: Direct command-line access
+- **HTTP API Service**: RESTful programmatic access
+- **Web Dashboard**: Visual monitoring and control
+- **MCP Protocol**: Agent-to-agent optimization coordination
+
+## 7. Usage Patterns
+
+### 7.1 Basic Optimization
+```bash
+cortex-mem optimize --strategy full --user-id user123 --dry-run
+```
+
+### 7.2 Programmatic Access
+```typescript
+const store = createOptimizationStore();
+await store.runOptimization({
+ strategy: 'deduplication',
+ filters: { user_id: 'user123' },
+ dry_run: true
+});
+```
+
+### 7.3 Monitoring Progress
+```rust
+let status = optimizer.get_optimization_status().await?;
+for s in status {
+ println!("Job {}: {}%", s.id, s.progress);
+}
+```
+
+## 8. Best Practices
+
+### 8.1 Safety Considerations
+- Always use `dry_run` mode first to preview changes
+- Implement appropriate backup procedures before major optimizations
+- Monitor system performance during intensive operations
+- Use incremental strategies for production environments
+
+### 8.2 Performance Optimization
+- Schedule heavy optimizations during off-peak hours
+- Use targeted filters to reduce scope
+- Adjust batch sizes based on system resources
+- Monitor memory usage during execution
+
+### 8.3 Configuration Guidelines
+- Tune duplicate threshold based on use case (0.7-0.9 typical range)
+- Adjust quality thresholds according to content standards
+- Set appropriate timeout values for long-running operations
+- Enable detailed logging for troubleshooting
+
+## 9. Metrics and Monitoring
+
+The system provides comprehensive metrics including:
+- Issues found by type and severity
+- Actions performed count
+- Execution duration
+- Success/failure rates
+- Resource utilization statistics
+
+These metrics are accessible through both API endpoints and the web dashboard, enabling continuous monitoring of memory health and optimization effectiveness.
\ No newline at end of file
diff --git a/litho.docs/4.Deep-Exploration/Storage Integration Domain.md b/litho.docs/4.Deep-Exploration/Storage Integration Domain.md
new file mode 100644
index 0000000..a984bd6
--- /dev/null
+++ b/litho.docs/4.Deep-Exploration/Storage Integration Domain.md
@@ -0,0 +1,504 @@
+# Storage Integration Domain Technical Documentation
+
+## 1. Overview
+
+The **Storage Integration Domain** is a critical infrastructure component within the Cortex-Mem system, responsible for persistent storage and retrieval of AI agent memories using vector database technology. This domain provides reliable, high-performance access to memory data through vector-based operations, enabling semantic search capabilities that are essential for intelligent agent behavior.
+
+As a key enabler of the system's core functionality, the Storage Integration Domain handles all interactions with the Qdrant vector database, managing the complete lifecycle of memory records including creation, search, update, and deletion operations. The domain ensures data consistency, schema integrity, and efficient query performance while abstracting the complexities of vector database operations from higher-level business logic components.
+
+### Key Characteristics
+- **Primary Function**: Persistent storage and retrieval of memory vectors and metadata
+- **Core Technology**: Qdrant vector database integration
+- **Architecture Pattern**: Repository pattern with trait-based abstraction
+- **Data Model**: Vector embeddings with rich metadata payload
+- **Critical Dependencies**: Configuration Management, LLM Integration domains
+
+## 2. Architecture and Design
+
+### 2.1 Component Structure
+
+The Storage Integration Domain follows a clean separation of concerns between interface abstraction and concrete implementation:
+
+```
+┌─────────────────┐ ┌──────────────────────────────┐
+│ │ │ │
+│ VectorStore │<───>│ QdrantVectorStore │
+│ (Trait) │ │ (Implementation) │
+│ │ │ │
+└─────────────────┘ └──────────────────────────────┘
+ │
+ ▼
+ ┌─────────────────┐
+ │ │
+ │ Qdrant DB │
+ │ (External) │
+ │ │
+ └─────────────────┘
+```
+
+#### Core Components:
+- **`VectorStore` Trait**: Abstract interface defining the contract for vector storage operations
+- **`QdrantVectorStore` Struct**: Concrete implementation handling Qdrant-specific operations
+- **Qdrant Client**: Underlying Rust client library for Qdrant API communication
+
+### 2.2 Key Design Principles
+
+#### Abstraction Through Traits
+The domain employs Rust's trait system to define a clear contract for vector storage operations, enabling potential future support for alternative vector databases:
+
+```rust
+#[async_trait]
+pub trait VectorStore: Send + Sync + dyn_clone::DynClone {
+ async fn insert(&self, memory: &Memory) -> Result<()>;
+ async fn search(&self, query_vector: &[f32], filters: &Filters, limit: usize) -> Result>;
+ // ... other methods
+}
+```
+
+This design allows the system to maintain flexibility while currently focusing on Qdrant as the primary backend.
+
+#### Auto-Configuration and Schema Management
+The implementation includes sophisticated auto-configuration capabilities that detect embedding dimensions and ensure collection schema compatibility:
+
+- **Auto-detection**: Dynamically determines embedding dimension by testing with the LLM client
+- **Schema Verification**: Validates collection configuration matches expected dimensions
+- **Automatic Provisioning**: Creates collections if they don't exist with proper configuration
+
+#### Type Safety and Error Handling
+The domain implements comprehensive error handling through the `MemoryError` enum, providing meaningful error messages for various failure scenarios:
+
+```rust
+#[derive(Error, Debug)]
+pub enum MemoryError {
+ #[error("Vector store error: {0}")]
+ VectorStore(#[from] qdrant_client::QdrantError),
+ #[error("Configuration error: {0}")]
+ Config(String),
+ #[error("Parse error: {0}")]
+ Parse(String),
+}
+```
+
+## 3. Technical Implementation Details
+
+### 3.1 Core Operations
+
+#### 3.1.1 Insert Operation
+The insert operation persists a memory record in the vector database:
+
+```rust
+async fn insert(&self, memory: &Memory) -> Result<()> {
+ let point = self.memory_to_point(memory);
+
+ let upsert_request = UpsertPoints {
+ collection_name: self.collection_name.clone(),
+ points: vec![point],
+ ..Default::default()
+ };
+
+ self.client.upsert_points(upsert_request).await?;
+ Ok(())
+}
+```
+
+Key aspects:
+- Converts `Memory` objects to Qdrant `PointStruct` format
+- Uses upsert semantics to handle both create and update operations
+- Includes comprehensive logging for debugging purposes
+
+#### 3.1.2 Search Operation
+The search operation enables semantic retrieval of memories based on vector similarity:
+
+```rust
+async fn search_with_threshold(
+ &self,
+ query_vector: &[f32],
+ filters: &Filters,
+ limit: usize,
+ score_threshold: Option,
+) -> Result> {
+ let filter = self.filters_to_qdrant_filter(filters);
+
+ let search_points = SearchPoints {
+ collection_name: self.collection_name.clone(),
+ vector: query_vector.to_vec(),
+ limit: limit as u64,
+ filter,
+ with_payload: Some(true.into()),
+ with_vectors: Some(true.into()),
+ score_threshold: score_threshold.map(|t| t as f32),
+ ..Default::default()
+ };
+
+ let response = self.client.search_points(search_points).await?;
+ // Convert results to ScoredMemory objects
+}
+```
+
+Features:
+- Supports similarity threshold filtering to return only relevant results
+- Combines vector similarity with structured metadata filtering
+- Returns scored results ordered by relevance
+
+### 3.2 Data Mapping and Serialization
+
+#### 3.2.1 Memory-to-Point Conversion
+The domain handles bidirectional conversion between domain objects and database representations:
+
+```rust
+fn memory_to_point(&self, memory: &Memory) -> PointStruct {
+ let mut payload = HashMap::new();
+
+ // Basic fields
+ payload.insert("content".to_string(), memory.content.clone().into());
+ payload.insert("created_at".to_string(), memory.created_at.to_rfc3339().into());
+
+ // Metadata fields
+ if let Some(user_id) = &memory.metadata.user_id {
+ payload.insert("user_id".to_string(), user_id.clone().into());
+ }
+
+ // Enum types converted to strings
+ let memory_type_str = format!("{:?}", memory.metadata.memory_type);
+ payload.insert("memory_type".to_string(), memory_type_str.into());
+
+ // Complex types serialized to JSON
+ if !memory.metadata.entities.is_empty() {
+ let entities_json = serde_json::to_string(&memory.metadata.entities).unwrap_or_default();
+ payload.insert("entities".to_string(), entities_json.into());
+ }
+
+ PointStruct::new(memory.id.clone(), memory.embedding.clone(), payload)
+}
+```
+
+#### 3.2.2 Payload Structure
+The Qdrant payload includes both direct values and serialized complex types:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `content` | string | Original memory text content |
+| `created_at` | string (RFC3339) | Creation timestamp |
+| `updated_at` | string (RFC3339) | Last update timestamp |
+| `user_id`, `agent_id`, etc. | string | Identifier fields |
+| `memory_type` | string | Enum value as string |
+| `importance_score` | number | Float value for salience |
+| `entities`, `topics` | string (JSON) | Serialized arrays |
+| `custom_*` | various | Custom metadata fields |
+
+### 3.3 Filtering System
+
+The domain implements a comprehensive filtering system that translates application-level filters to Qdrant conditions:
+
+```rust
+fn filters_to_qdrant_filter(&self, filters: &Filters) -> Option {
+ let mut conditions = Vec::new();
+
+ // Exact match conditions
+ if let Some(user_id) = &filters.user_id {
+ conditions.push(field_condition("user_id", user_id));
+ }
+
+ // Range conditions
+ if let Some(min_importance) = filters.min_importance {
+ conditions.push(range_condition("importance_score", min_importance as f64, None));
+ }
+
+ // Array membership conditions
+ if let Some(topics) = &filters.topics {
+ let topic_conditions: Vec = topics.iter()
+ .map(|topic| field_condition_with_text_match("topics", topic))
+ .collect();
+
+ conditions.push(filter_condition_with_should(topic_conditions));
+ }
+
+ if conditions.is_empty() {
+ None
+ } else {
+ Some(Filter { must: conditions, ..Default::default() })
+ }
+}
+```
+
+Supported filter types include:
+- **Exact matching**: User ID, agent ID, run ID, memory type
+- **Range queries**: Importance score, timestamps
+- **Array membership**: Entities, topics
+- **Custom fields**: Arbitrary key-value pairs with keyword matching
+
+### 3.4 Health Monitoring
+
+The domain includes health checking capabilities to monitor database connectivity:
+
+```rust
+async fn health_check(&self) -> Result {
+ match self.client.health_check().await {
+ Ok(_) => Ok(true),
+ Err(e) => {
+ error!("Qdrant health check failed: {}", e);
+ Ok(false)
+ }
+ }
+}
+```
+
+This allows higher-level components to detect and respond to storage system issues.
+
+## 4. Configuration and Initialization
+
+### 4.1 Configuration Parameters
+
+The domain is configured through the `qdrant` section in `config.toml`:
+
+```toml
+[qdrant]
+url = "http://localhost:6334"
+collection_name = "cortex-mem-hewlett_drawn"
+# embedding_dim = 1024 # Optional, auto-detected if omitted
+timeout_secs = 30
+```
+
+Key configuration options:
+- **url**: Qdrant server endpoint
+- **collection_name**: Target collection for memory storage
+- **embedding_dim**: Expected embedding dimension (optional)
+- **timeout_secs**: Request timeout duration
+
+### 4.2 Initialization Process
+
+The initialization process follows this sequence:
+
+1. **Configuration Loading**: Read Qdrant settings from config file
+2. **Client Creation**: Initialize Qdrant client with connection parameters
+3. **Dimension Detection**:
+ - Use configured dimension if specified
+ - Otherwise, auto-detect by generating test embedding via LLM client
+4. **Collection Provisioning**:
+ - Check if collection exists
+ - Create with proper dimension and cosine distance metric if missing
+ - Verify existing collection has compatible schema
+5. **Health Verification**: Confirm connectivity before returning instance
+
+Two factory methods support different initialization scenarios:
+
+```rust
+// Standard initialization with explicit configuration
+pub async fn new(config: &QdrantConfig) -> Result
+
+// Enhanced initialization with auto-detection capabilities
+pub async fn new_with_llm_client(
+ config: &QdrantConfig,
+ llm_client: &dyn crate::llm::LLMClient,
+) -> Result
+```
+
+## 5. Integration Points
+
+### 5.1 Upstream Dependencies
+
+#### Configuration Management Domain
+The Storage Integration Domain depends on the Configuration Management Domain for its operational parameters:
+
+```rust
+use crate::config::QdrantConfig;
+// ...
+let client = Qdrant::from_url(&config.url).build()?;
+```
+
+This dependency ensures consistent configuration across the system and supports environment-specific deployments.
+
+#### LLM Integration Domain
+During initialization with auto-detection, the domain interacts with the LLM client to determine embedding dimensions:
+
+```rust
+if store.embedding_dim.is_none() {
+ let test_embedding = llm_client.embed("test").await?;
+ let detected_dim = test_embedding.len();
+ store.embedding_dim = Some(detected_dim);
+}
+```
+
+This tight integration ensures compatibility between the embedding model and vector database schema.
+
+### 5.2 Downstream Consumers
+
+#### Memory Management Domain
+The primary consumer of the Storage Integration Domain is the Memory Management Domain, which uses it for persistence operations:
+
+```rust
+// In memory manager
+self.vector_store.insert(memory).await?;
+let results = self.vector_store.search(query_vector, &filters, limit).await?;
+```
+
+This relationship enables the core memory lifecycle operations while maintaining separation of concerns.
+
+#### Access Interface Domain
+All access interfaces (CLI, HTTP API, MCP) ultimately rely on storage operations for data persistence, creating an indirect dependency chain through the Memory Management Domain.
+
+## 6. Operational Considerations
+
+### 6.1 Performance Characteristics
+
+#### Latency Factors
+- **Network latency**: Between application and Qdrant server
+- **Vector dimension**: Higher dimensions increase computation time
+- **Collection size**: Larger collections may impact search performance
+- **Filter complexity**: Complex filters require more processing
+
+#### Optimization Strategies
+- **Indexing**: Qdrant automatically creates indexes for efficient search
+- **Batch operations**: Support for bulk inserts/updates
+- **Caching**: Potential for higher-level caching of frequent queries
+- **Connection pooling**: Reuse of client connections
+
+### 6.2 Reliability and Resilience
+
+#### Error Handling
+The domain implements robust error handling for various failure scenarios:
+
+- **Connection failures**: Retry logic with exponential backoff
+- **Serialization errors**: Graceful handling of malformed data
+- **Schema mismatches**: Clear error messages for dimension conflicts
+- **Rate limiting**: Respect for server rate limits
+
+#### Recovery Procedures
+- **Automatic reconnection**: Client handles transient network issues
+- **Idempotent operations**: Safe retry of failed operations
+- **Health monitoring**: Early detection of service degradation
+
+### 6.3 Scalability Considerations
+
+#### Horizontal Scaling
+- **Stateless service layer**: Multiple instances can share same database
+- **Sharding support**: Qdrant supports collection sharding for large datasets
+- **Load balancing**: External load balancers can distribute requests
+
+#### Capacity Planning
+- **Storage requirements**: Approximately 1KB per memory record plus index overhead
+- **Memory usage**: Qdrant requires sufficient RAM for vector indexing
+- **Compute resources**: CPU-intensive during indexing and search operations
+
+## 7. Usage Examples
+
+### 7.1 Basic Operations
+
+#### Creating a New Instance
+```rust
+let config = QdrantConfig {
+ url: "http://localhost:6334".to_string(),
+ collection_name: "my_memories".to_string(),
+ embedding_dim: Some(1024),
+ timeout_secs: 30,
+};
+
+let store = QdrantVectorStore::new(&config).await?;
+```
+
+#### Inserting a Memory
+```rust
+let memory = Memory::new(
+ "Hello, world!".to_string(),
+ vec![0.1, 0.2, 0.3], // embedding
+ MemoryMetadata::new(MemoryType::Conversational),
+);
+
+store.insert(&memory).await?;
+```
+
+#### Searching Memories
+```rust
+let query_embedding = vec![0.15, 0.25, 0.35]; // from LLM
+let filters = Filters::new().for_user("user123");
+
+let results = store
+ .search(&query_embedding, &filters, 10)
+ .await?;
+
+for scored_memory in results {
+ println!("Score: {}, Content: {}",
+ scored_memory.score,
+ scored_memory.memory.content);
+}
+```
+
+### 7.2 Advanced Scenarios
+
+#### Filtered Semantic Search
+```rust
+let filters = Filters::new()
+ .with_memory_type(MemoryType::Factual)
+ .with_min_importance(0.7)
+ .with_topics(vec!["science".to_string()])
+ .with_custom_field("category", "research");
+
+let results = store
+ .search_with_threshold(
+ &query_embedding,
+ &filters,
+ 20,
+ Some(0.6) // minimum similarity score
+ )
+ .await?;
+```
+
+#### Batch Operations
+While not explicitly shown in the current implementation, the underlying Qdrant client supports batch operations that could be exposed through enhanced APIs:
+
+```rust
+// Conceptual batch insert
+let batch_request = UpsertPoints {
+ points: memories.iter().map(|m| store.memory_to_point(m)).collect(),
+ // ... other parameters
+};
+```
+
+## 8. Future Enhancements
+
+### 8.1 Planned Improvements
+
+#### Alternative Backend Support
+The trait-based design positions the system well for supporting additional vector databases:
+
+- **Weaviate**: GraphQL-native vector database
+- **Pinecone**: Fully managed vector database service
+- **Chroma**: Lightweight, embeddable vector store
+
+#### Enhanced Query Capabilities
+Potential additions include:
+- **Hybrid search**: Combining keyword and vector search
+- **Faceted navigation**: Aggregation-based exploration
+- **Time-series optimizations**: Specialized handling for temporal data
+
+#### Advanced Management Features
+- **Automated compaction**: Periodic optimization of storage
+- **Backup/restore**: Comprehensive data protection
+- **Migration tools**: Schema evolution support
+
+### 8.2 Integration Opportunities
+
+#### Multi-tenancy Support
+Enhancements to support isolated storage for multiple tenants:
+- **Namespace isolation**: Separate collections per tenant
+- **Access control**: Integration with authentication systems
+- **Resource quotas**: Per-tenant usage limits
+
+#### Hybrid Storage Patterns
+Combining vector storage with traditional databases:
+- **Cold storage**: Archiving older memories to cheaper storage
+- **Materialized views**: Pre-computed aggregations for analytics
+- **Change data capture**: Real-time synchronization with other systems
+
+## 9. Summary
+
+The Storage Integration Domain serves as the persistence backbone of the Cortex-Mem system, providing reliable, high-performance access to AI agent memories through vector database technology. Its thoughtful design balances abstraction with practical implementation details, ensuring both flexibility and performance.
+
+Key strengths of the current implementation include:
+- **Clean separation of concerns** through trait-based abstraction
+- **Robust auto-configuration** that handles dimension detection and schema management
+- **Comprehensive filtering** that combines vector similarity with structured queries
+- **Resilient error handling** with meaningful diagnostics
+- **Tight integration** with the broader system architecture
+
+The domain successfully addresses the core requirements of AI agent memory management while providing a solid foundation for future enhancements and scalability. Its role as the persistent storage layer makes it a critical component in enabling intelligent, context-aware agent behavior across extended interaction sequences.
\ No newline at end of file
diff --git a/litho.docs/5.Boundary-Interfaces.md b/litho.docs/5.Boundary-Interfaces.md
index f49bdbd..5ee7ef7 100644
--- a/litho.docs/5.Boundary-Interfaces.md
+++ b/litho.docs/5.Boundary-Interfaces.md
@@ -6,497 +6,262 @@ This document describes the system's external invocation interfaces, including C
### cortex-mem-cli
-**Description**: Rust Agent Memory System CLI that provides commands for adding, searching, listing, and deleting memories, as well as optimization-related operations.
+**Description**: Main CLI interface for memory management operations
**Source File**: `cortex-mem-cli/src/main.rs`
**Arguments**:
-- `config` (PathBuf): optional - Path to the configuration file, defaults to config.toml (default: `config.toml`)
-
-**Options**:
-
-- `content, c`(String): required - Content to store as memory
-- `user_id, u`(String): optional - User ID for the memory
-- `agent_id, a`(String): optional - Agent ID for the memory
-- `memory_type, t`(String): optional - Memory type (conversational, procedural, factual) (default: `conversational`)
-- `query, q`(String): optional - Search query (optional - if not provided, will use only metadata filters)
-- `topics`(Vec): optional - Topics filter (comma-separated)
-- `keywords`(Vec): optional - Keywords filter (comma-separated)
-- `limit, l`(usize): optional - Maximum number of results (default: `10`)
-- `id`(String): required - Memory ID to delete
+- `command` (Commands): required - Subcommand to execute (add, delete, list, search)
+- `config` (PathBuf): optional - Path to configuration file (default: `config.toml`)
**Usage Examples**:
```bash
-# Add a new memory\ncortex-mem-cli add --content "Meeting notes" --user-id user123 --memory-type conversational
+cortex-mem-cli add --content "Meeting notes" --user-id user123
```
```bash
-# Search for memories\ncortex-mem-cli search --query "project status" --user-id user123 --limit 5
+cortex-mem-cli search "project timeline" --user-id user123
```
```bash
-# List all memories for a user\ncortex-mem-cli list --user-id user123
-```
-
-```bash
-# Delete a memory\ncortex-mem-cli delete mem_abc123
-```
-
-```bash
-# Optimize memory database\ncortex-mem-cli optimize
+cortex-mem-cli list --agent-id agent456 --limit 10
```
### cortex-mem-mcp
-**Description**: MCP server for Cortex Memo memory management system that serves as an MCP service over stdio with configuration and agent identifier options.
+**Description**: MCP server for memory operations over stdio transport
**Source File**: `cortex-mem-mcp/src/main.rs`
**Arguments**:
-- `config` (PathBuf): optional - Path to the configuration file (default: `config.toml`)
-- `agent` (String): optional - Agent identifier for memory operations
+- `config` (PathBuf): optional - Path to the TOML configuration file (default: `config.toml`)
+- `agent` (String): optional - Optional agent identifier used for scoping memory operations
**Usage Examples**:
```bash
-# Start MCP server with default config\ncortex-mem-mcp
+cortex-mem-mcp --config /path/to/config.toml
```
```bash
-# Start MCP server with custom config and agent ID\ncortex-mem-mcp --config /path/to/config.toml --agent my-agent-001
+cortex-mem-mcp --agent agent123
```
-### cortex-mem-evaluation
+### cortex-mem-tars
-**Description**: Evaluation framework for assessing Cortex-Mem core capabilities including recall, effectiveness, performance, and dataset generation/validation.
+**Description**: Terminal-based interactive AI assistant with memory integration
-**Source File**: `examples/cortex-mem-evaluation/src/main.rs`
+**Source File**: `examples/cortex-mem-tars/src/main.rs`
-**Options**:
+**Arguments**:
-- `config, c`(PathBuf): optional - Configuration file path (default: `config/evaluation_config.toml`)
-- `output_dir, o`(PathBuf): optional - Output directory for results (default: `results`)
-- `dataset_type, d`(String): optional - Data set type: recall, effectiveness, all (default: `all`)
-- `size, s`(usize): optional - Dataset size (default: `100`)
-- `use_lab_data`(bool): optional - Whether to use laboratory data (default: `true`)
-- `dataset_path, p`(PathBuf): required - Path to the dataset
-- `dataset_type, t`(String): required - Dataset type: recall, effectiveness
+- `config` (PathBuf): optional - Configuration file path parameter (default: `config.toml`)
**Usage Examples**:
```bash
-# Run full evaluation\ncortex-mem-evaluation run --config config/evaluation_config.toml --output-dir results
-```
-
-```bash
-# Run recall evaluation only\ncortex-mem-evaluation recall --config config/evaluation_config.toml
-```
-
-```bash
-# Generate test dataset\ncortex-mem-evaluation generate-dataset --dataset-type all --size 1000
-```
-
-```bash
-# Validate dataset\ncortex-mem-evaluation validate-dataset --dataset-path data/test_dataset.json --dataset-type recall
+cortex-mem-tars --config config.prod.toml
```
### cortex-mem-service
-**Description**: HTTP Service for Rust Agent Memory System that provides RESTful API endpoints for memory management and optimization tasks.
+**Description**: HTTP service for memory operations
**Source File**: `cortex-mem-service/src/main.rs`
-**Arguments**:
-
-- `config` (PathBuf): optional - Path to the configuration file (default: `config.toml`)
-
**Usage Examples**:
```bash
-# Start HTTP service with default config\ncortex-mem-service
-```
-
-```bash
-# Start HTTP service with custom config\ncortex-mem-service --config /path/to/custom-config.toml
-```
-
-### multi-round-interactive
-
-**Description**: Multi-round interactive conversation with a memory-enabled agent using TUI interface, supporting graceful shutdown with background memory persistence.
-
-**Source File**: `examples/cortex-mem-tars/src/main.rs`
-
-**Arguments**:
-
-- `config` (PathBuf): optional - Path to the configuration file (default: `config.toml`)
-
-**Usage Examples**:
-
-```bash
-# Start interactive session with default config\nmulti-round-interactive
-```
-
-```bash
-# Start interactive session with custom config\nmulti-round-interactive --config /path/to/config.toml
+cortex-mem-service
```
## API Interfaces
### GET /health
-**Description**: Health check endpoint to verify system health including vector store and LLM service connectivity.
+**Description**: Health check endpoint that verifies the overall system health including vector store and LLM service
**Source File**: `cortex-mem-service/src/handlers.rs`
-**Response Format**: {\n "status": "healthy" | "unhealthy",\n "vector_store": boolean,\n "llm_service": boolean,\n "timestamp": string\n}
+**Response Format**: Json
### POST /memories
-**Description**: Create a new memory with content and optional metadata such as user ID, agent ID, and memory type.
-
-**Source File**: `cortex-mem-service/src/handlers.rs`
-
-**Request Format**: {\n "content": string,\n "user_id"?: string,\n "agent_id"?: string,\n "run_id"?: string,\n "actor_id"?: string,\n "role"?: string,\n "memory_type"?: string,\n "custom"?: Record\n}
-
-**Response Format**: {\n "message": string,\n "id": string\n}
-
-### GET /memories
-
-**Description**: List memories with optional filtering by user ID, agent ID, run ID, actor ID, memory type, and limit.
+**Description**: Creates a new memory with support for both simple content and conversation-based procedural memory
**Source File**: `cortex-mem-service/src/handlers.rs`
-**Request Format**: ?user_id=string&agent_id=string&run_id=string&actor_id=string&memory_type=string&limit=number
-
-**Response Format**: {\n "total": number,\n "memories": Array<{\n "id": string,\n "content": string,\n "metadata": {\n "user_id"?: string,\n "agent_id"?: string,\n "run_id"?: string,\n "actor_id"?: string,\n "role"?: string,\n "memory_type": string,\n "hash": string,\n "custom": Record\n },\n "created_at": string,\n "updated_at": string\n }>\n}
-
-### POST /memories/search
+**Request Format**: Json
-**Description**: Search memories by semantic similarity using a query string with optional filters and similarity threshold.
-
-**Source File**: `cortex-mem-service/src/handlers.rs`
-
-**Request Format**: {\n "query": string,\n "user_id"?: string,\n "agent_id"?: string,\n "run_id"?: string,\n "actor_id"?: string,\n "memory_type"?: string,\n "limit"?: number,\n "similarity_threshold"?: number\n}
-
-**Response Format**: {\n "total": number,\n "results": Array<{\n "memory": MemoryResponse,\n "score": number\n }>\n}
+**Response Format**: Json
### GET /memories/{id}
-**Description**: Retrieve a specific memory by its unique identifier.
+**Description**: Retrieves a specific memory by its ID
**Source File**: `cortex-mem-service/src/handlers.rs`
-**Response Format**: {\n "id": string,\n "content": string,\n "metadata": {\n "user_id"?: string,\n "agent_id"?: string,\n "run_id"?: string,\n "actor_id"?: string,\n "role"?: string,\n "memory_type": string,\n "hash": string,\n "custom": Record\n },\n "created_at": string,\n "updated_at": string\n}
+**Response Format**: Json
### PUT /memories/{id}
-**Description**: Update the content of an existing memory identified by its ID.
+**Description**: Updates an existing memory with new content
**Source File**: `cortex-mem-service/src/handlers.rs`
-**Request Format**: {\n "content": string\n}
+**Request Format**: Json
-**Response Format**: {\n "message": string,\n "id": string\n}
+**Response Format**: Json
### DELETE /memories/{id}
-**Description**: Delete a memory by its unique identifier.
+**Description**: Deletes a memory by its ID
**Source File**: `cortex-mem-service/src/handlers.rs`
-**Response Format**: {\n "message": string,\n "id": string\n}
-
-### POST /optimization
-
-**Description**: Start a new memory optimization task with optional parameters for memory type, user/agent IDs, and optimization strategy.
+**Response Format**: Json
-**Source File**: `cortex-mem-service/src/optimization_handlers.rs`
+### POST /search
-**Request Format**: {\n "memory_type"?: string,\n "user_id"?: string,\n "agent_id"?: string,\n "run_id"?: string,\n "actor_id"?: string,\n "similarity_threshold"?: number,\n "dry_run"?: boolean,\n "verbose"?: boolean,\n "strategy"?: string,\n "aggressive"?: boolean,\n "timeout_minutes"?: number\n}
+**Description**: Searches memories using similarity matching with optional filters
-**Response Format**: {\n "success": boolean,\n "data"?: any,\n "error"?: {\n "code": string,\n "message": string\n },\n "timestamp": string\n}
+**Source File**: `cortex-mem-service/src/handlers.rs`
-### GET /optimization/{jobId}
+**Request Format**: Json
-**Description**: Get the current status of a specific optimization job by its job identifier.
+**Response Format**: Json
-**Source File**: `cortex-mem-service/src/optimization_handlers.rs`
+### GET /memories
-**Response Format**: {\n "success": boolean,\n "data"?: {\n "job_id": string,\n "status": string,\n "progress": number,\n "current_phase": string,\n "logs": string[],\n "result"?: OptimizationResult,\n "start_time": string,\n "end_time"?: string,\n "duration"?: number\n },\n "error"?: {\n "code": string,\n "message": string\n },\n "timestamp": string\n}
+**Description**: Lists memories with optional filtering and pagination
-### POST /optimization/{jobId}/cancel
+**Source File**: `cortex-mem-service/src/handlers.rs`
-**Description**: Cancel a running optimization job identified by its job ID.
+**Request Format**: Query
-**Source File**: `cortex-mem-service/src/optimization_handlers.rs`
+**Response Format**: Json
-**Response Format**: {\n "success": boolean,\n "data"?: {\n "job_id": string,\n "message": string,\n "status": "cancelled",\n "cancelled_at": string\n },\n "error"?: {\n "code": string,\n "message": string\n },\n "timestamp": string\n}
+### POST /batch-delete
-### GET /optimization/history
+**Description**: Performs batch deletion of multiple memories
-**Description**: Retrieve historical records of optimization jobs with optional pagination and filtering.
+**Source File**: `cortex-mem-service/src/handlers.rs`
-**Source File**: `cortex-mem-service/src/optimization_handlers.rs`
+**Request Format**: Json
-**Request Format**: ?limit=number&offset=number&status=string&start_date=string&end_date=string
+**Response Format**: Json
-**Response Format**: {\n "success": boolean,\n "data"?: {\n "total": number,\n "history": Array<{\n "job_id": string,\n "status": string,\n "start_time": string,\n "end_time"?: string,\n "duration"?: number,\n "logs_count": number,\n "has_result": boolean\n }>,\n "pagination": {\n "limit": number,\n "offset": number,\n "total": number\n }\n },\n "error"?: {\n "code": string,\n "message": string\n },\n "timestamp": string\n}
+### POST /batch-update
-### GET /optimization/statistics
+**Description**: Performs batch update of multiple memories
-**Description**: Get statistical information about optimization jobs including success rates, durations, and processed memories.
+**Source File**: `cortex-mem-service/src/handlers.rs`
-**Source File**: `cortex-mem-service/src/optimization_handlers.rs`
+**Request Format**: Json
-**Response Format**: {\n "success": boolean,\n "data"?: {\n "total_jobs": number,\n "successful_jobs": number,\n "failed_jobs": number,\n "cancelled_jobs": number,\n "total_memories_processed": number,\n "avg_duration": number,\n "last_run"?: string\n },\n "error"?: {\n "code": string,\n "message": string\n },\n "timestamp": string\n}
+**Response Format**: Json
-### POST /optimization/analyze
+### POST /optimization
-**Description**: Analyze potential optimization opportunities in preview mode without making changes (dry-run).
+**Description**: Initiates a new optimization task with the specified parameters
**Source File**: `cortex-mem-service/src/optimization_handlers.rs`
-**Request Format**: {\n "memory_type"?: string,\n "user_id"?: string,\n "agent_id"?: string,\n "run_id"?: string,\n "actor_id"?: string,\n "similarity_threshold"?: number\n}
+**Request Format**: Json
-**Response Format**: {\n "success": boolean,\n "data"?: {\n "issues": Array,\n "summary": {\n "total_issues": number,\n "total_affected_memories": number,\n "estimated_savings_mb": number,\n "estimated_duration_minutes": number\n },\n "recommendations": Array<{\n "type": string,\n "action": string,\n "priority": string\n }>\n },\n "error"?: {\n "code": string,\n "message": string\n },\n "timestamp": string\n}
+**Response Format**: Json
-### POST /optimization/cleanup
+### GET /optimization/{job_id}
-**Description**: Clean up old optimization history records based on age criteria.
+**Description**: Retrieves the current status and progress of a specific optimization job
**Source File**: `cortex-mem-service/src/optimization_handlers.rs`
-**Request Format**: {\n "max_age_days": number\n}
-
-**Response Format**: {\n "success": boolean,\n "data"?: {\n "deleted": number,\n "remaining": number,\n "message": string\n },\n "error"?: {\n "code": string,\n "message": string\n },\n "timestamp": string\n}
-
-### GET /llm/status
-
-**Description**: Get detailed status of LLM services including completion and embedding model availability and latency.
-
-**Source File**: `cortex-mem-service/src/handlers.rs`
-
-**Response Format**: {\n "overall_status": string,\n "completion_model": {\n "available": boolean,\n "provider": string,\n "model_name": string,\n "latency_ms"?: number,\n "error_message"?: string,\n "last_check": string\n },\n "embedding_model": {\n "available": boolean,\n "provider": string,\n "model_name": string,\n "latency_ms"?: number,\n "error_message"?: string,\n "last_check": string\n },\n "timestamp": string\n}
+**Response Format**: Json
-### GET /llm/health-check
+### POST /optimization/{job_id}/cancel
-**Description**: Simple health check for LLM service availability.
+**Description**: Cancels a running optimization job if it hasn't completed
-**Source File**: `cortex-mem-service/src/handlers.rs`
+**Source File**: `cortex-mem-service/src/optimization_handlers.rs`
-**Response Format**: {\n "completion_model_available": boolean,\n "embedding_model_available": boolean,\n "timestamp": string\n}
+**Response Format**: Json
## Router Routes
### /
-**Description**: Dashboard page showing overall system status and key metrics.
-
-**Source File**: `cortex-mem-insights/src/routes/+layout.svelte`
-
-### /memories
-
-**Description**: Memory Browser page for viewing, searching, and managing stored memories.
+**Description**: Dashboard page component that manages dashboard state, loads data on mount, calculates derived metrics, handles errors with fallback data
-**Source File**: `cortex-mem-insights/src/routes/+layout.svelte`
-
-### /analytics
-
-**Description**: Analytics page for visualizing memory usage patterns, statistics, and trends.
-
-**Source File**: `cortex-mem-insights/src/routes/+layout.svelte`
+**Source File**: `cortex-mem-insights/src/routes/+page.svelte`
### /optimization
-**Description**: Optimization Panel page for managing memory optimization tasks and viewing their status.
+**Description**: Optimization dashboard component that manages complete optimization lifecycle (initiation, execution, monitoring), provides UI for strategy selection and configuration
-**Source File**: `cortex-mem-insights/src/routes/+layout.svelte`
+**Source File**: `cortex-mem-insights/src/routes/optimization/+page.svelte`
-### /monitor
+### /layout
-**Description**: System Monitor page for monitoring real-time system health, performance metrics, and logs.
+**Description**: Layout component providing consistent structure across all pages, imports global styles, tracks current route path via $page store
**Source File**: `cortex-mem-insights/src/routes/+layout.svelte`
## Integration Suggestions
-### CLI
-
-Integrate CLI tools into automated workflows and scripts for batch memory operations and system maintenance.
-
-**Example Code**:
-
-```
-#!/bin/bash\n# Script to regularly optimize memory database\necho "Starting daily memory optimization..."\ncortex-mem-cli optimize --config /etc/cortex-mem/config.toml\necho "Memory optimization completed at $(date)"
-```
-
-**Best Practices**:
-
-- Use configuration files instead of command-line arguments for production deployments
-- Implement proper error handling when calling CLI tools programmatically
-- Schedule optimization tasks during low-usage periods to minimize impact on performance
-- Monitor exit codes and log outputs for automated task debugging
-
### API
-Integrate with the REST API for building custom applications and dashboards that interact with the memory system.
+Use the TypeScript client for seamless integration with the Cortex Memory Service API
**Example Code**:
```
-import axios from 'axios';
-
-// Configure API client
-const api = axios.create({
- baseURL: 'http://localhost:3000',
- timeout: 10000,
-});
-
-// Function to search memories
-async function searchMemories(query, filters = {}) {
- try {
- const response = await api.post('/memories/search', {
- query,
- ...filters
- });
- return response.data;
- } catch (error) {
- console.error('Search failed:', error);
- throw error;
- }
-}
-
-// Function to create a memory
-async function createMemory(content, metadata = {}) {
- try {
- const response = await api.post('/memories', {
- content,
- ...metadata
- });
- return response.data;
- } catch (error) {
- console.error('Create memory failed:', error);
- throw error;
- }
-}
+import { cortexMemService } from './integrations/cortex-mem';\n\nconst client = new cortexMemService('http://localhost:8080');\nconst response = await client.listMemories({ user_id: 'user123', limit: 10 });
```
**Best Practices**:
-- Use environment variables for API base URLs to support different deployment environments
-- Implement retry logic with exponential backoff for transient failures
-- Handle authentication if added in future versions
-- Validate responses before processing to ensure data integrity
-- Monitor API usage and implement rate limiting in client code
+- Use environment variables for API endpoints
+- Implement proper error handling around API calls
+- Cache responses when appropriate to reduce latency
+- Use typed interfaces for type safety
-### Config
+### CLI
-Configure the system through TOML configuration files to customize behavior across different environments.
+Integrate CLI commands into your deployment pipelines or scripts
**Example Code**:
```
-# config.toml
-[server]
-host = "0.0.0.0"
-port = 3000
-cors_origins = ["http://localhost:5173", "https://your-app.com"]
-
-[qdrant]
-url = "http://localhost:6334"
-collection_name = "memories"
-embedding_dim = 1536
-timeout_secs = 30
-
-[llm]
-api_base_url = "https://api.openai.com/v1"
-api_key = "${LLM_API_KEY}"
-model_efficient = "gpt-3.5-turbo"
-temperature = 0.7
-max_tokens = 1000
-
-[memory]
-max_memories = 10000
-similarity_threshold = 0.65
-max_search_results = 50
-auto_summary_threshold = 32768
-auto_enhance = true
-deduplicate = true
-merge_threshold = 0.75
-search_similarity_threshold = 0.70
-
-[logging]
-enabled = true
-log_directory = "logs"
-level = "info"
+#!/bin/bash\n# Script to backup memories regularly\nUSER_ID="${1:-user123}"\nBACKUP_DIR="/backups/memories/$(date +%Y%m%d)"\n\nmkdir -p "$BACKUP_DIR"\n\ncortex-mem-cli list --user-id "$USER_ID" --format json > "$BACKUP_DIR/memories.json"\necho "Backup completed: $BACKUP_DIR/memories.json"
```
**Best Practices**:
-- Use environment variable substitution in configuration files for sensitive data
-- Keep separate configuration files for development, staging, and production environments
-- Set appropriate similarity thresholds based on your use case (higher for precision, lower for recall)
-- Configure CORS origins properly to allow legitimate frontend applications while preventing unauthorized access
-- Regularly review and update configuration settings as system requirements evolve
+- Use configuration files for complex setups
+- Implement logging in wrapper scripts
+- Handle exit codes appropriately
+- Use absolute paths in production environments
-### Security
+### Monitoring
-Secure the system against common vulnerabilities by implementing proper authentication, input validation, and secure configuration practices.
+Set up monitoring for system health and performance metrics
**Example Code**:
```
-# Secure configuration example
-
-# 1. Use environment variables for secrets
-cat > .env << 'EOL'
-LLM_API_KEY=sk-your-secret-key-here
-DATABASE_PASSWORD=strong-db-password
-EOL
-
-# 2. Update config.toml to use environment variables
-[llm]
-api_key = "${LLM_API_KEY}" # Will be loaded from environment
-
-# 3. Set proper file permissions
-chmod 600 .env # Read/write for owner only
-chmod 644 config.toml # Readable by owner, readable by group/others
-
-# 4. Example nginx reverse proxy configuration for additional security
-server {
- listen 80;
- server_name cortex-mem.example.com;
-
- location / {
- # Rate limiting: max 100 requests per minute per IP
- limit_req zone=api_limit burst=20 nodelay;
-
- # Forward to backend service
- proxy_pass http://localhost:3000;
- proxy_set_header Host $host;
- proxy_set_header X-Real-IP $remote_addr;
-
- # Security headers
- add_header X-Frame-Options "DENY";
- add_header X-Content-Type-Options "nosniff";
- add_header Content-Security-Policy "default-src 'self';";
- }
-}
+import { systemApi } from '$lib/api/client';\n\nsetInterval(async () => {\n try {\n const status = await systemApi.getStatus();\n if (status.overall_status !== 'healthy') {\n // Send alert or notification\n console.error('System health degraded:', status);\n }\n } catch (error) {\n console.error('Failed to check system status:', error);\n }\n}, 30000); // Check every 30 seconds
```
**Best Practices**:
-- Never commit API keys or other secrets to version control
-- Use HTTPS in production to encrypt data in transit
-- Implement rate limiting to prevent abuse
-- Validate and sanitize all inputs to prevent injection attacks
-- Keep dependencies updated to address known security vulnerabilities
-- Use role-based access control when available
-- Regularly audit system logs for suspicious activity
-- Implement proper CORS policies to restrict origin access
+- Monitor both application and system metrics
+- Set up alerts for critical failures
+- Log monitoring data for trend analysis
+- Use exponential backoff for retry logic
---
diff --git a/litho.docs/__Litho_Summary_Brief__.md b/litho.docs/__Litho_Summary_Brief__.md
index ab89ea9..51ca4d3 100644
--- a/litho.docs/__Litho_Summary_Brief__.md
+++ b/litho.docs/__Litho_Summary_Brief__.md
@@ -1,24 +1,24 @@
# Project Analysis Brief Report
-Generation Time: 2025-12-18 03:35:17 UTC
+Generation Time: 2025-12-30 11:34:01 UTC
## Execution Overview
-**Total Execution Time**: 1148.89 seconds
+**Total Execution Time**: 1761.37 seconds
**Phase Timing**:
-- Documentation: 531.05s (46.2%)
-- Research: 389.49s (33.9%)
-- Preprocessing: 228.35s (19.9%)
+- Documentation: 1075.94s (61.1%)
+- Research: 660.22s (37.5%)
+- Preprocessing: 25.21s (1.4%)
- Output: 0.00s (0.0%)
## Cache Effectiveness Overview
-**Cache Hit Rate**: 82.1% 🟢 Excellent
-**Time Saved**: 831.1 seconds
-**Tokens Saved**: 249575 input + 108543 output = 358118 total
-**Cost Savings**: $0.2010
-**Efficiency Improvement**: 0.7x
-**Cost-Benefit**: $0.000175/second
+**Cache Hit Rate**: 86.8% 🟢 Excellent
+**Time Saved**: 881.0 seconds
+**Tokens Saved**: 290514 input + 116766 output = 407280 total
+**Cost Savings**: $0.2280
+**Efficiency Improvement**: 0.5x
+**Cost-Benefit**: $0.000129/second
## Research Data Overview
@@ -33,27 +33,32 @@ Successfully collected four types of research materials according to Prompt temp
## Memory Storage Overview
-**Total Storage Size**: 1693607 bytes
+**Total Storage Size**: 1652867 bytes
**Number of Storage Scopes**: 4
### Main Storage Distribution (Top 3)
-- **preprocess**: 1533048 bytes (90.5%)
-- **documentation**: 99706 bytes (5.9%)
-- **studies_research**: 60817 bytes (3.6%)
+- **preprocess**: 1391134 bytes (84.2%)
+- **documentation**: 166050 bytes (10.0%)
+- **studies_research**: 95646 bytes (5.8%)
## Document Generation Overview
-**Number of Generated Documents**: 5
+**Number of Generated Documents**: 10
**Document Types**:
- - Boundary Interfaces
- - Architecture Description
- Core Workflows
- Key Modules and Components Research Report_Memory Management Domain
+ - Boundary Interfaces
- Project Overview
+ - Key Modules and Components Research Report_Access Interface Domain
+ - Key Modules and Components Research Report_Memory Optimization Domain
+ - Key Modules and Components Research Report_Configuration Management Domain
+ - Key Modules and Components Research Report_Storage Integration Domain
+ - Architecture Description
+ - Key Modules and Components Research Report_LLM Integration Domain
## Overall Assessment
**Data Completeness**: 100.0% 🟢 Complete
-**Cache Efficiency**: 82.1% 🟢 Efficient
-**Execution Efficiency**: 1148.89s 🔴 Slow
+**Cache Efficiency**: 86.8% 🟢 Efficient
+**Execution Efficiency**: 1761.37s 🔴 Slow
**Document Generation**: Completed 🟢 Success
diff --git a/litho.docs/__Litho_Summary_Detail__.md b/litho.docs/__Litho_Summary_Detail__.md
index bcfbb16..d19271d 100644
--- a/litho.docs/__Litho_Summary_Detail__.md
+++ b/litho.docs/__Litho_Summary_Detail__.md
@@ -1,31 +1,31 @@
# Project Analysis Summary Report (Full Version)
-Generation Time: 2025-12-18 03:35:17 UTC
+Generation Time: 2025-12-30 11:34:01 UTC
## Execution Timing Statistics
-- **Total Execution Time**: 1148.89 seconds
-- **Preprocessing Phase**: 228.35 seconds (19.9%)
-- **Research Phase**: 389.49 seconds (33.9%)
-- **Document Generation Phase**: 531.05 seconds (46.2%)
+- **Total Execution Time**: 1761.37 seconds
+- **Preprocessing Phase**: 25.21 seconds (1.4%)
+- **Research Phase**: 660.22 seconds (37.5%)
+- **Document Generation Phase**: 1075.94 seconds (61.1%)
- **Output Phase**: 0.00 seconds (0.0%)
- **Summary Generation Time**: 0.002 seconds
## Cache Performance Statistics and Savings
### Performance Metrics
-- **Cache Hit Rate**: 82.1%
-- **Total Operations**: 179
-- **Cache Hits**: 147 times
-- **Cache Misses**: 32 times
-- **Cache Writes**: 33 times
+- **Cache Hit Rate**: 86.8%
+- **Total Operations**: 174
+- **Cache Hits**: 151 times
+- **Cache Misses**: 23 times
+- **Cache Writes**: 24 times
### Savings
-- **Inference Time Saved**: 831.1 seconds
-- **Tokens Saved**: 249575 input + 108543 output = 358118 total
-- **Estimated Cost Savings**: $0.2010
-- **Performance Improvement**: 82.1%
-- **Efficiency Improvement Ratio**: 0.7x (saved time / actual execution time)
+- **Inference Time Saved**: 881.0 seconds
+- **Tokens Saved**: 290514 input + 116766 output = 407280 total
+- **Estimated Cost Savings**: $0.2280
+- **Performance Improvement**: 86.8%
+- **Efficiency Improvement Ratio**: 0.5x (saved time / actual execution time)
## Core Research Data Summary
@@ -36,77 +36,71 @@ Provides core objectives, user roles, and system boundary information for the pr
```json
{
- "business_value": "Enables AI agents to maintain long-term context and knowledge across interactions, improving their effectiveness, consistency, and intelligence by providing reliable memory management capabilities with optimization, analysis, and visualization tools.",
+ "business_value": "Enables AI agents to maintain context across interactions through persistent memory storage, retrieval, and optimization capabilities, improving agent intelligence and user experience.",
"confidence_score": 0.95,
"external_systems": [
{
- "description": "Vector database used for storing and retrieving memories using semantic search",
+ "description": "Vector database used for storing and retrieving memory embeddings",
"interaction_type": "Database Storage",
"name": "Qdrant"
},
{
- "description": "External language model APIs used for processing and understanding memory content",
+ "description": "LLM service used for text generation, embeddings, and memory analysis",
"interaction_type": "API Integration",
- "name": "LLM Services"
+ "name": "OpenAI"
},
{
- "description": "Web browsers and other HTTP clients that interact with the insights dashboard",
- "interaction_type": "User Interface",
- "name": "HTTP Clients"
- },
- {
- "description": "Terminal applications that use the CLI tools to interact with the memory system",
- "interaction_type": "User Interface",
- "name": "Command Line Interface"
+ "description": "Alternative memory system used for evaluation and comparison purposes",
+ "interaction_type": "Benchmarking",
+ "name": "LangMem"
}
],
- "project_description": "A comprehensive memory management system for AI agents that provides persistent, searchable, and optimizable memory storage with advanced features like semantic search, deduplication, optimization, and analytics.",
+ "project_description": "A comprehensive memory management system for AI agents that provides persistent, searchable, and optimizable memory storage with multiple access interfaces.",
"project_name": "cortex-mem",
"project_type": "FullStackApp",
"system_boundary": {
"excluded_components": [
- "Core LLM model training",
- "Vector embedding model development",
- "Operating system level resource management",
- "Network infrastructure provisioning"
+ "Core AI agent logic",
+ "Application-specific business rules",
+ "User interface design for end applications",
+ "Network infrastructure management"
],
"included_components": [
- "Memory CRUD operations",
- "Semantic search with vector embeddings",
- "Memory optimization and deduplication",
- "Analytics and visualization dashboard",
- "REST API service",
- "Command-line interface",
- "Evaluation framework"
- ],
- "scope": "The cortex-mem system provides a complete memory management solution for AI agents, including storage, retrieval, optimization, and analysis capabilities."
+ "Memory storage and retrieval",
+ "Semantic search capabilities",
+ "Memory optimization engine",
+ "Multiple access interfaces (CLI, API, MCP)",
+ "Web-based monitoring dashboard",
+ "Configuration management"
+ ],
+ "scope": "The cortex-mem system provides memory management capabilities for AI agents through multiple interfaces including CLI, HTTP API, MCP protocol, and web dashboard. It handles memory storage, retrieval, search, and optimization while integrating with external LLM and vector database services."
},
"target_users": [
{
- "description": "Software engineers building AI-powered applications that require persistent memory capabilities",
- "name": "AI Agent Developers",
+ "description": "Intelligent software agents that require persistent memory to maintain context across conversations and tasks",
+ "name": "AI Agents",
"needs": [
- "Integrate memory management into AI agents",
- "Access memories through APIs and CLI",
- "Monitor agent memory performance"
+ "Store conversation history",
+ "Retrieve relevant memories",
+ "Optimize memory usage"
]
},
{
- "description": "Operations personnel managing AI agent infrastructure",
- "name": "System Administrators",
+ "description": "Software engineers integrating memory capabilities into AI applications",
+ "name": "Developers",
"needs": [
- "Monitor system health and status",
- "Optimize memory usage",
- "Analyze memory patterns and trends"
+ "API access to memory functions",
+ "Configuration flexibility",
+ "Integration with existing systems"
]
},
{
- "description": "Researchers evaluating AI agent memory systems",
- "name": "Research Scientists",
+ "description": "Operators managing AI agent infrastructure",
+ "name": "System Administrators",
"needs": [
- "Benchmark memory system performance",
- "Evaluate recall and effectiveness",
- "Generate test datasets for validation"
+ "Monitoring tools",
+ "Optimization capabilities",
+ "Maintenance interfaces"
]
}
]
@@ -118,116 +112,158 @@ Provides high-level domain division, module relationships, and core business pro
```json
{
- "architecture_summary": "The cortex-mem system follows a modular, layered architecture with clear separation of concerns. It centers around a core memory management engine (cortex-mem-core) that provides fundamental capabilities for storing, retrieving, and optimizing memories using vector databases and LLMs. This core is exposed through multiple interfaces: a REST API service (cortex-mem-service), a command-line interface (cortex-mem-cli), an MCP protocol adapter (cortex-mem-mcp), and various example applications. A comprehensive insights dashboard (cortex-mem-insights) provides visualization and analytics. The system includes a sophisticated evaluation framework for testing performance and effectiveness. Configuration is centrally managed and supports TOML-based external configuration files.",
+ "architecture_summary": "The cortex-mem system follows a modular microservices architecture with clear separation of concerns across multiple access interfaces (CLI, HTTP API, MCP) and core memory processing logic. The system integrates external services like Qdrant for vector storage and OpenAI for LLM capabilities while providing multiple entry points for different user types. Frontend and backend components are cleanly separated with TypeScript-based web interface communicating via RESTful APIs to Rust-based backend services. Configuration is centralized and shared across components, enabling consistent behavior across different interfaces.",
"business_flows": [
{
- "description": "Core process for creating, retrieving, updating, and deleting memories in the system",
- "entry_point": "HTTP API endpoint /memories or CLI command 'add'",
+ "description": "Process for creating new memories through various interfaces, involving content analysis, embedding generation, and storage.",
+ "entry_point": "User or agent initiates memory creation via CLI command, API call, or MCP tool invocation",
"importance": 9.5,
"involved_domains_count": 4,
- "name": "Memory Management Process",
+ "name": "Memory Creation Process",
"steps": [
{
- "code_entry_point": "cortex-mem-service/src/handlers.rs:create_memory or cortex-mem-cli/src/commands/add.rs",
- "domain_module": "Memory Management Domain",
- "operation": "Receive create memory request via API or CLI",
+ "code_entry_point": "cortex-mem-cli/src/commands/add.rs",
+ "domain_module": "Access Interface Domain",
+ "operation": "Receive memory creation request with content from user",
"step": 1,
- "sub_module": "Memory Operations"
+ "sub_module": "CLI Interface"
},
{
- "code_entry_point": "cortex-mem-core/src/llm/client.rs",
- "domain_module": "Memory Storage Domain",
- "operation": "Generate embeddings for memory content using LLM client",
+ "code_entry_point": "cortex-mem-core/src/memory/classification.rs",
+ "domain_module": "Memory Management Domain",
+ "operation": "Classify memory type based on content and context",
"step": 2,
- "sub_module": "Vector Store Integration"
+ "sub_module": "Memory Types System"
},
{
- "code_entry_point": "cortex-mem-core/src/vector_store/qdrant.rs",
- "domain_module": "Memory Storage Domain",
- "operation": "Store memory with embeddings in Qdrant vector database",
+ "code_entry_point": "cortex-mem-core/src/llm/client.rs",
+ "domain_module": "LLM Integration Domain",
+ "operation": "Generate embedding for the memory content using LLM",
"step": 3,
- "sub_module": "Vector Store Integration"
+ "sub_module": "LLM Client"
+ },
+ {
+ "code_entry_point": "cortex-mem-core/src/memory/extractor.rs",
+ "domain_module": "LLM Integration Domain",
+ "operation": "Extract facts, entities, and keywords from content",
+ "step": 4,
+ "sub_module": "Information Extraction"
},
{
"code_entry_point": "cortex-mem-core/src/memory/manager.rs",
"domain_module": "Memory Management Domain",
- "operation": "Return success response with memory ID to client",
- "step": 4,
- "sub_module": "Memory Lifecycle Management"
+ "operation": "Store memory with embedding, metadata, and extracted information",
+ "step": 5,
+ "sub_module": "Memory CRUD Operations"
+ },
+ {
+ "code_entry_point": "cortex-mem-core/src/vector_store/qdrant.rs",
+ "domain_module": "Storage Integration Domain",
+ "operation": "Persist memory vector in Qdrant database",
+ "step": 6,
+ "sub_module": "Vector Store"
}
]
},
{
- "description": "Process for analyzing and improving the quality of stored memories through deduplication, relevance tuning, and quality enhancement",
- "entry_point": "HTTP API endpoint /optimization/start or CLI command 'optimize'",
- "importance": 8.0,
- "involved_domains_count": 4,
- "name": "Memory Optimization Process",
+ "description": "Process for searching and retrieving relevant memories based on query, supporting both semantic and metadata-based search.",
+ "entry_point": "User or agent requests memory search via CLI, API, or MCP interface",
+ "importance": 9.0,
+ "involved_domains_count": 3,
+ "name": "Memory Retrieval Process",
"steps": [
{
- "code_entry_point": "cortex-mem-service/src/optimization_handlers.rs:start_optimization or cortex-mem-cli/src/commands/optimize.rs",
- "domain_module": "Optimization Domain",
- "operation": "Receive optimization request with optional filters and strategy",
+ "code_entry_point": "cortex-mem-service/src/handlers.rs",
+ "domain_module": "Access Interface Domain",
+ "operation": "Receive search request with query and optional filters",
"step": 1,
- "sub_module": "Optimization Orchestration"
+ "sub_module": "HTTP API Service"
},
{
- "code_entry_point": "cortex-mem-core/src/memory/optimization_detector.rs",
- "domain_module": "Memory Analysis Domain",
- "operation": "Analyze existing memories to detect duplicates, low-quality entries, and relevance issues",
+ "code_entry_point": "cortex-mem-core/src/llm/client.rs",
+ "domain_module": "LLM Integration Domain",
+ "operation": "Generate embedding for the search query",
"step": 2,
- "sub_module": "Memory Quality Assessment"
+ "sub_module": "LLM Client"
},
{
- "code_entry_point": "cortex-mem-core/src/memory/optimizer.rs",
- "domain_module": "Optimization Domain",
- "operation": "Execute optimization plan using LLM to improve memory quality and remove duplicates",
+ "code_entry_point": "cortex-mem-core/src/memory/manager.rs",
+ "domain_module": "Memory Management Domain",
+ "operation": "Search for similar memories using vector similarity",
"step": 3,
- "sub_module": "Optimization Execution"
+ "sub_module": "Semantic Search"
},
{
- "code_entry_point": "cortex-mem-core/src/memory/result_reporter.rs",
- "domain_module": "Optimization Domain",
- "operation": "Generate optimization report and return results to client",
+ "code_entry_point": "cortex-mem-core/src/memory/manager.rs",
+ "domain_module": "Memory Management Domain",
+ "operation": "Apply metadata filters to refine results",
"step": 4,
- "sub_module": "Optimization Reporting"
+ "sub_module": "Memory CRUD Operations"
+ },
+ {
+ "code_entry_point": "cortex-mem-core/src/vector_store/qdrant.rs",
+ "domain_module": "Storage Integration Domain",
+ "operation": "Retrieve memory details from Qdrant database",
+ "step": 5,
+ "sub_module": "Vector Store"
+ },
+ {
+ "code_entry_point": "cortex-mem-service/src/handlers.rs",
+ "domain_module": "Access Interface Domain",
+ "operation": "Return ranked search results to caller",
+ "step": 6,
+ "sub_module": "HTTP API Service"
}
]
},
{
- "description": "Process for finding relevant memories based on semantic queries or metadata filters",
- "entry_point": "HTTP API endpoint /memories/search or CLI command 'search'",
- "importance": 9.0,
- "involved_domains_count": 3,
- "name": "Memory Search Process",
+ "description": "Process for analyzing and improving memory collection quality through deduplication, relevance filtering, and other optimization strategies.",
+ "entry_point": "User initiates optimization via CLI optimize command or web dashboard",
+ "importance": 8.5,
+ "involved_domains_count": 4,
+ "name": "Memory Optimization Process",
"steps": [
{
- "code_entry_point": "cortex-mem-service/src/handlers.rs:search_memories or cortex-mem-cli/src/commands/search.rs",
- "domain_module": "Memory Management Domain",
- "operation": "Receive search request with query text and/or metadata filters",
+ "code_entry_point": "cortex-mem-cli/src/commands/optimize.rs",
+ "domain_module": "Access Interface Domain",
+ "operation": "Receive optimization request with strategy and filters",
"step": 1,
- "sub_module": "Memory Operations"
+ "sub_module": "CLI Interface"
},
{
- "code_entry_point": "cortex-mem-core/src/llm/client.rs",
- "domain_module": "Memory Storage Domain",
- "operation": "Generate embedding for query text using LLM client",
+ "code_entry_point": "cortex-mem-core/src/memory/optimization_analyzer.rs",
+ "domain_module": "Memory Optimization Domain",
+ "operation": "Analyze memory collection for issues like duplicates and low-quality entries",
"step": 2,
- "sub_module": "Vector Store Integration"
+ "sub_module": "Optimization Engine"
},
{
- "code_entry_point": "cortex-mem-core/src/vector_store/qdrant.rs",
- "domain_module": "Memory Storage Domain",
- "operation": "Perform semantic search in Qdrant vector database using query embedding",
+ "code_entry_point": "cortex-mem-core/src/memory/updater.rs",
+ "domain_module": "LLM Integration Domain",
+ "operation": "Use LLM analysis to identify similar memories for potential merging",
"step": 3,
- "sub_module": "Vector Store Integration"
+ "sub_module": "Memory Intelligence"
+ },
+ {
+ "code_entry_point": "cortex-mem-core/src/memory/optimization_plan.rs",
+ "domain_module": "Memory Optimization Domain",
+ "operation": "Generate optimization plan with recommended actions",
+ "step": 4,
+ "sub_module": "Optimization Strategies"
},
{
"code_entry_point": "cortex-mem-core/src/memory/manager.rs",
"domain_module": "Memory Management Domain",
- "operation": "Apply metadata filters and return ranked list of matching memories",
- "step": 4,
- "sub_module": "Memory Retrieval"
+ "operation": "Execute optimization plan by updating, merging, or deleting memories",
+ "step": 5,
+ "sub_module": "Memory CRUD Operations"
+ },
+ {
+ "code_entry_point": "cortex-mem-insights/src/lib/stores/optimization.ts",
+ "domain_module": "Access Interface Domain",
+ "operation": "Report optimization results and statistics to user",
+ "step": 6,
+ "sub_module": "Optimization UI"
}
]
}
@@ -236,13 +272,11 @@ Provides high-level domain division, module relationships, and core business pro
"domain_modules": [
{
"code_paths": [
- "cortex-mem-core/src/memory/manager.rs",
- "cortex-mem-core/src/memory/updater.rs",
- "cortex-mem-core/src/memory/classification.rs",
- "cortex-mem-core/src/memory/importance.rs"
+ "cortex-mem-core/src/memory/",
+ "cortex-mem-core/src/types.rs"
],
- "complexity": 8.0,
- "description": "Core domain responsible for managing the lifecycle of memories including creation, retrieval, update, deletion, and basic operations. This domain provides the primary interface for interacting with stored memories and handles the orchestration of memory-related operations.",
+ "complexity": 9.0,
+ "description": "Core domain responsible for managing the lifecycle of memories including creation, retrieval, updating, and deletion. This domain handles both direct memory operations and complex scenarios involving semantic search and metadata filtering.",
"domain_type": "Core Business Domain",
"importance": 9.5,
"name": "Memory Management Domain",
@@ -251,73 +285,377 @@ Provides high-level domain division, module relationships, and core business pro
"code_paths": [
"cortex-mem-core/src/memory/manager.rs",
"cortex-mem-service/src/handlers.rs",
- "cortex-mem-cli/src/commands/*.rs"
+ "cortex-mem-cli/src/commands/add.rs",
+ "cortex-mem-cli/src/commands/delete.rs"
],
- "description": "Handles CRUD operations for memories and basic manipulation functions",
- "importance": 9.0,
+ "description": "Handles basic create, read, update, and delete operations for memory entries",
+ "importance": 9.5,
"key_functions": [
"Create memory",
- "Retrieve memory by ID",
+ "Retrieve memory",
"Update memory",
- "Delete memory",
- "List memories with filtering"
+ "Delete memory"
],
- "name": "Memory Operations"
+ "name": "Memory CRUD Operations"
},
{
"code_paths": [
"cortex-mem-core/src/memory/manager.rs",
- "cortex-mem-core/src/memory/updater.rs"
+ "cortex-mem-core/src/vector_store/qdrant.rs",
+ "cortex-mem-cli/src/commands/search.rs"
+ ],
+ "description": "Provides semantic search capabilities using vector embeddings and similarity matching",
+ "importance": 9.0,
+ "key_functions": [
+ "Vector-based search",
+ "Metadata filtering",
+ "Relevance scoring"
+ ],
+ "name": "Semantic Search"
+ },
+ {
+ "code_paths": [
+ "cortex-mem-core/src/types.rs",
+ "cortex-mem-core/src/memory/classification.rs"
+ ],
+ "description": "Manages classification and handling of different memory types (conversational, procedural, factual, etc.)",
+ "importance": 8.5,
+ "key_functions": [
+ "Type classification",
+ "Content parsing",
+ "Metadata extraction"
+ ],
+ "name": "Memory Types System"
+ }
+ ]
+ },
+ {
+ "code_paths": [
+ "cortex-mem-cli/",
+ "cortex-mem-service/",
+ "cortex-mem-mcp/",
+ "cortex-mem-insights/"
+ ],
+ "complexity": 8.0,
+ "description": "Provides multiple interfaces for interacting with the memory system, catering to different user types and integration scenarios.",
+ "domain_type": "Tool Support Domain",
+ "importance": 8.5,
+ "name": "Access Interface Domain",
+ "sub_modules": [
+ {
+ "code_paths": [
+ "cortex-mem-cli/src/main.rs",
+ "cortex-mem-cli/src/commands/"
],
- "description": "Manages the full lifecycle of memories from creation to archival or deletion",
+ "description": "Command-line interface for direct interaction with memory system",
"importance": 8.5,
"key_functions": [
- "Memory versioning",
- "Status tracking",
- "Archival policies",
+ "Command parsing",
+ "Interactive workflows",
"Batch operations"
],
- "name": "Memory Lifecycle Management"
+ "name": "CLI Interface"
},
{
"code_paths": [
- "cortex-mem-core/src/memory/manager.rs",
+ "cortex-mem-service/src/main.rs",
"cortex-mem-service/src/handlers.rs"
],
- "description": "Specialized functionality for retrieving memories based on various criteria",
+ "description": "RESTful API service for programmatic access to memory functions",
+ "importance": 9.0,
+ "key_functions": [
+ "Route handling",
+ "Request validation",
+ "Response formatting"
+ ],
+ "name": "HTTP API Service"
+ },
+ {
+ "code_paths": [
+ "cortex-mem-mcp/src/lib.rs",
+ "cortex-mem-mcp/src/main.rs"
+ ],
+ "description": "Memory Control Protocol interface for AI agent integration",
+ "importance": 8.5,
+ "key_functions": [
+ "Protocol handling",
+ "Tool routing",
+ "Agent communication"
+ ],
+ "name": "MCP Protocol Interface"
+ },
+ {
+ "code_paths": [
+ "cortex-mem-insights/src/server/index.ts",
+ "cortex-mem-insights/src/routes/"
+ ],
+ "description": "Web-based interface for monitoring and managing memory system",
+ "importance": 8.0,
+ "key_functions": [
+ "Data visualization",
+ "System monitoring",
+ "User interaction"
+ ],
+ "name": "Web Dashboard"
+ }
+ ]
+ },
+ {
+ "code_paths": [
+ "cortex-mem-core/src/memory/optimizer.rs",
+ "cortex-mem-core/src/memory/optimization_*"
+ ],
+ "complexity": 8.5,
+ "description": "Responsible for maintaining memory quality and efficiency through various optimization strategies including deduplication, relevance filtering, and quality improvement.",
+ "domain_type": "Core Business Domain",
+ "importance": 9.0,
+ "name": "Memory Optimization Domain",
+ "sub_modules": [
+ {
+ "code_paths": [
+ "cortex-mem-core/src/memory/optimizer.rs",
+ "cortex-mem-core/src/memory/optimization_analyzer.rs"
+ ],
+ "description": "Core optimization logic that analyzes and improves memory collections",
+ "importance": 9.0,
+ "key_functions": [
+ "Issue detection",
+ "Plan generation",
+ "Execution tracking"
+ ],
+ "name": "Optimization Engine"
+ },
+ {
+ "code_paths": [
+ "cortex-mem-core/src/types/optimization.rs",
+ "cortex-mem-core/src/memory/optimization_plan.rs"
+ ],
+ "description": "Implementation of various optimization approaches (full, incremental, deduplication, etc.)",
+ "importance": 8.5,
+ "key_functions": [
+ "Strategy selection",
+ "Filter application",
+ "Action planning"
+ ],
+ "name": "Optimization Strategies"
+ },
+ {
+ "code_paths": [
+ "cortex-mem-insights/src/lib/stores/optimization.ts",
+ "cortex-mem-insights/src/routes/optimization/+page.svelte"
+ ],
+ "description": "User interface for managing optimization workflows",
+ "importance": 8.0,
+ "key_functions": [
+ "Job initiation",
+ "Progress monitoring",
+ "Results review"
+ ],
+ "name": "Optimization UI"
+ }
+ ]
+ },
+ {
+ "code_paths": [
+ "cortex-mem-core/src/llm/"
+ ],
+ "complexity": 8.5,
+ "description": "Manages interaction with Large Language Models for extracting insights from content and making intelligent decisions about memory operations.",
+ "domain_type": "Core Business Domain",
+ "importance": 9.0,
+ "name": "LLM Integration Domain",
+ "sub_modules": [
+ {
+ "code_paths": [
+ "cortex-mem-core/src/llm/client.rs"
+ ],
+ "description": "Client for communicating with LLM services",
"importance": 9.0,
"key_functions": [
- "Get memory by ID",
- "List memories with pagination",
- "Filter by metadata",
- "Batch retrieval"
+ "Text completion",
+ "Embedding generation",
+ "Structured extraction"
+ ],
+ "name": "LLM Client"
+ },
+ {
+ "code_paths": [
+ "cortex-mem-core/src/llm/extractor_types.rs",
+ "cortex-mem-core/src/memory/extractor.rs"
+ ],
+ "description": "Extracts structured information from unstructured content",
+ "importance": 8.5,
+ "key_functions": [
+ "Fact extraction",
+ "Entity recognition",
+ "Keyword identification"
+ ],
+ "name": "Information Extraction"
+ },
+ {
+ "code_paths": [
+ "cortex-mem-core/src/memory/updater.rs",
+ "cortex-mem-core/src/memory/prompts.rs"
+ ],
+ "description": "Uses LLM analysis to make decisions about memory operations",
+ "importance": 8.5,
+ "key_functions": [
+ "Content analysis",
+ "Similarity assessment",
+ "Operation recommendation"
+ ],
+ "name": "Memory Intelligence"
+ }
+ ]
+ },
+ {
+ "code_paths": [
+ "cortex-mem-config/src/lib.rs",
+ "config.toml"
+ ],
+ "complexity": 6.5,
+ "description": "Centralized configuration system that manages settings for all components across the application.",
+ "domain_type": "Infrastructure Domain",
+ "importance": 8.0,
+ "name": "Configuration Management Domain",
+ "sub_modules": [
+ {
+ "code_paths": [
+ "cortex-mem-config/src/lib.rs"
+ ],
+ "description": "Defines the schema and structure of configuration data",
+ "importance": 8.0,
+ "key_functions": [
+ "Type definition",
+ "Default values",
+ "Validation"
+ ],
+ "name": "Config Structure"
+ },
+ {
+ "code_paths": [
+ "cortex-mem-config/src/lib.rs",
+ "cortex-mem-core/src/init/mod.rs"
+ ],
+ "description": "Loads configuration from files and environment",
+ "importance": 7.5,
+ "key_functions": [
+ "File parsing",
+ "Fallback resolution",
+ "Error handling"
+ ],
+ "name": "Config Loading"
+ },
+ {
+ "code_paths": [
+ "examples/lomoco-evaluation/src/cortex_mem/config_utils.py"
+ ],
+ "description": "Validates configuration integrity and completeness",
+ "importance": 7.0,
+ "key_functions": [
+ "Schema checking",
+ "Required field verification",
+ "Value validation"
+ ],
+ "name": "Config Validation"
+ }
+ ]
+ },
+ {
+ "code_paths": [
+ "cortex-mem-core/src/vector_store/"
+ ],
+ "complexity": 7.5,
+ "description": "Handles persistence of memories using vector databases and ensures reliable storage operations.",
+ "domain_type": "Infrastructure Domain",
+ "importance": 8.5,
+ "name": "Storage Integration Domain",
+ "sub_modules": [
+ {
+ "code_paths": [
+ "cortex-mem-core/src/vector_store/qdrant.rs"
+ ],
+ "description": "Manages vector-based storage and retrieval",
+ "importance": 8.5,
+ "key_functions": [
+ "Embedding storage",
+ "Similarity search",
+ "Index management"
+ ],
+ "name": "Vector Store"
+ },
+ {
+ "code_paths": [
+ "cortex-mem-core/src/vector_store/qdrant.rs"
+ ],
+ "description": "Specific implementation for Qdrant vector database",
+ "importance": 8.0,
+ "key_functions": [
+ "Connection management",
+ "Collection operations",
+ "Query execution"
],
- "name": "Memory Retrieval"
+ "name": "Qdrant Integration"
}
]
}
],
"domain_relations": [
{
- "description": "Memory Management Domain depends on Memory Storage Domain to persist and retrieve memories from the vector database. The manager components call into vector store implementations to perform actual storage operations.",
+ "description": "Memory Management relies on Storage Integration for persistent storage of memory vectors and metadata in Qdrant database",
"from_domain": "Memory Management Domain",
- "relation_type": "Service Dependency",
- "strength": 9.5,
- "to_domain": "Memory Storage Domain"
+ "relation_type": "Data Dependency",
+ "strength": 9.0,
+ "to_domain": "Storage Integration Domain"
},
{
- "description": "Optimization processes require access to managed memories through the Memory Management Domain's APIs to analyze and modify existing memory entries.",
- "from_domain": "Optimization Domain",
+ "description": "Memory operations use LLM Integration for content analysis, embedding generation, and intelligent decision-making during memory updates",
+ "from_domain": "Memory Management Domain",
"relation_type": "Service Call",
"strength": 8.5,
+ "to_domain": "LLM Integration Domain"
+ },
+ {
+ "description": "Optimization processes depend on Memory Management for retrieving memories to analyze and applying changes after optimization",
+ "from_domain": "Memory Optimization Domain",
+ "relation_type": "Service Call",
+ "strength": 9.0,
"to_domain": "Memory Management Domain"
},
{
- "description": "The insights dashboard needs to retrieve memory data from the Memory Management Domain to display in visualizations and analytics views.",
- "from_domain": "Insights & Analytics Domain",
- "relation_type": "Data Dependency",
- "strength": 8.0,
+ "description": "All access interfaces (CLI, HTTP API, MCP, Web) depend on Memory Management as the primary business logic layer for executing memory operations",
+ "from_domain": "Access Interface Domain",
+ "relation_type": "Service Call",
+ "strength": 9.5,
"to_domain": "Memory Management Domain"
+ },
+ {
+ "description": "LLM client configuration (API keys, endpoints) is provided by the centralized configuration system",
+ "from_domain": "LLM Integration Domain",
+ "relation_type": "Configuration Dependency",
+ "strength": 8.0,
+ "to_domain": "Configuration Management Domain"
+ },
+ {
+ "description": "Vector store connection parameters and settings are configured through the centralized configuration system",
+ "from_domain": "Storage Integration Domain",
+ "relation_type": "Configuration Dependency",
+ "strength": 8.5,
+ "to_domain": "Configuration Management Domain"
+ },
+ {
+ "description": "Optimization strategies and thresholds can be configured through the configuration system",
+ "from_domain": "Memory Optimization Domain",
+ "relation_type": "Configuration Dependency",
+ "strength": 7.5,
+ "to_domain": "Configuration Management Domain"
+ },
+ {
+ "description": "Interface-specific settings like server ports, logging levels, and feature flags are managed through configuration",
+ "from_domain": "Access Interface Domain",
+ "relation_type": "Configuration Dependency",
+ "strength": 8.0,
+ "to_domain": "Configuration Management Domain"
}
]
}
@@ -329,20 +667,20 @@ Contains static analysis results of the codebase and business process analysis.
```json
{
"main_workflow": {
- "description": "The core workflow for creating, retrieving, updating, and deleting memories in the system. This process begins with a user or application initiating a memory operation through either the HTTP API endpoint or CLI command. The system then processes the request by generating embeddings for the memory content using an LLM client, storing the memory with its embeddings in the Qdrant vector database, and returning a success response with the memory ID to the client.",
- "flowchart_mermaid": "graph TD\n A[User/Application] --> B{Initiate Memory Operation}\n B --> C[HTTP API / CLI Command]\n C --> D[Process Request]\n D --> E[Generate Embeddings via LLM Client]\n E --> F[Store in Qdrant Vector Database]\n F --> G[Return Success Response with Memory ID]\n G --> A",
- "name": "Memory Management Process"
+ "description": "The core workflow of the Cortex-Mem system revolves around managing AI agent memories through a comprehensive lifecycle of creation, storage, retrieval, and optimization. This workflow begins when a user or agent initiates memory creation via CLI, API, or MCP interface, triggering content analysis and classification. The system then generates embeddings using an LLM service and extracts structured information like facts, entities, and keywords before storing the memory with its metadata in a Qdrant vector database. For retrieval, users can perform semantic searches by query or use metadata filters, where the system generates an embedding for the search term and finds similar memories based on vector similarity. The workflow also includes periodic optimization processes that analyze memory quality, detect duplicates, and suggest merging or deletion to maintain efficiency.",
+ "flowchart_mermaid": "graph TD\n A[User/Agent Request] --> B{Operation Type}\n B -->|Create| C[Content Analysis & Classification]\n B -->|Search| D[Generate Query Embedding]\n B -->|Optimize| E[Analyze Memory Collection]\n \n C --> F[Extract Facts, Entities, Keywords]\n F --> G[Generate Memory Embedding]\n G --> H[Store in Qdrant DB]\n \n D --> I[Vector Similarity Search]\n I --> J[Apply Metadata Filters]\n J --> K[Return Ranked Results]\n \n E --> L[Detect Duplicates & Issues]\n L --> M[Generate Optimization Plan]\n M --> N[Execute Merge/Delete Operations]\n \n H --> P((Persistent Storage))\n K --> Q[Display Results]\n N --> R[Update Memory State]\n \n style A fill:#4CAF50,stroke:#388E3C\n style Q fill:#2196F3,stroke:#1976D2\n style P fill:#FF9800,stroke:#F57C00",
+ "name": "Memory Management Workflow"
},
"other_important_workflows": [
{
- "description": "A critical workflow for analyzing and improving the quality of stored memories through deduplication, relevance tuning, and quality enhancement. This process starts when a user or system initiates an optimization request with optional filters and strategy parameters. The system analyzes existing memories to detect issues like duplicates and low-quality entries, executes an optimization plan using LLMs to improve memory quality, and generates a comprehensive report of the optimization results.",
- "flowchart_mermaid": "graph TD\n A[User/System] --> B{Initiate Optimization}\n B --> C[Send Optimization Request with Filters]\n C --> D[Analyze Memories for Issues]\n D --> E[Detect Duplicates & Quality Problems]\n E --> F[Execute Optimization Plan via LLM]\n F --> G[Generate Optimization Report]\n G --> A",
- "name": "Memory Optimization Process"
+ "description": "This workflow handles the startup and configuration of the Cortex-Mem system across all interfaces. It begins with loading configuration from TOML files, which may include settings for the vector database (Qdrant), LLM services, HTTP server, and logging. The system then initializes tracing for comprehensive logging and creates a MemoryManager instance by auto-detecting the appropriate vector store and LLM client based on the configuration. During initialization, the system can automatically determine embedding dimensions either from existing LLM clients or through dynamic testing. Once initialized, the system exposes its functionality through multiple entry points: a CLI for direct interaction, an HTTP API service for programmatic access, an MCP server for AI agent integration, and a web dashboard for monitoring. Each interface shares the same underlying memory management system but provides tailored experiences for different user types.",
+ "flowchart_mermaid": "graph TD\n A[Load Configuration] --> B[Initialize Tracing & Logging]\n B --> C{Auto-detect Components}\n C --> D[Detect Vector Store]\n C --> E[Detect LLM Client]\n C --> F[Determine Embedding Dimension]\n \n D --> G[Create MemoryManager]\n E --> G\n F --> G\n \n G --> H[Expose Interfaces]\n H --> I[CLI Interface]\n H --> J[HTTP API Service]\n H --> K[MCP Server]\n H --> L[Web Dashboard]\n \n style A fill:#4CAF50,stroke:#388E3C\n style I fill:#2196F3,stroke:#1976D2\n style J fill:#2196F3,stroke:#1976D2\n style K fill:#2196F3,stroke:#1976D2\n style L fill:#2196F3,stroke:#1976D2",
+ "name": "System Initialization Workflow"
},
{
- "description": "The primary workflow for finding relevant memories based on semantic queries or metadata filters. This process begins when a user or application sends a search request containing query text and/or metadata filters. The system generates an embedding for the query text using an LLM client, performs a semantic search in the Qdrant vector database using the query embedding, applies additional metadata filters, and returns a ranked list of matching memories to the client.",
- "flowchart_mermaid": "graph TD\n A[User/Application] --> B{Initiate Search}\n B --> C[Send Search Request with Query]\n C --> D[Generate Query Embedding via LLM]\n D --> E[Semantic Search in Qdrant DB]\n E --> F[Apply Metadata Filters]\n F --> G[Return Ranked Matching Memories]\n G --> A",
- "name": "Memory Search Process"
+ "description": "The optimization workflow enables users to improve memory quality and efficiency through systematic analysis and improvement processes. Users initiate this workflow via CLI commands or the web dashboard, specifying optimization strategies such as full, incremental, deduplication, or quality-based optimization. The system first analyzes the memory collection to identify issues like duplicate entries, low-quality memories, or irrelevant content. Using LLM-powered analysis, it assesses similarity between memories based on embeddings and content, generating recommendations for merging related memories or deleting redundant ones. Before execution, the system provides a preview mode that shows the proposed changes and requires user confirmation, ensuring safety. When executed, the optimization process applies the plan by updating, merging, or deleting memories through the MemoryManager, while maintaining detailed logs of all actions taken. The workflow concludes with reporting statistics and results back to the user, including metrics on space reclaimed, duplicates removed, and overall quality improvements.",
+ "flowchart_mermaid": "graph TD\n A[User Initiates Optimization] --> B[Select Strategy & Filters]\n B --> C[Analyze Memory Collection]\n C --> D[Identify Duplicates & Issues]\n D --> E[Use LLM for Similarity Assessment]\n E --> F[Generate Optimization Plan]\n F --> G[Preview Changes & Confirm]\n G --> H{Execute?}\n H -->|Yes| I[Apply Changes via MemoryManager]\n H -->|No| J[Cancel]\n \n I --> K[Merge Related Memories]\n I --> L[Delete Redundant Entries]\n I --> M[Update Memory Metadata]\n \n K --> N[Log Actions & Metrics]\n L --> N\n M --> N\n \n N --> O[Report Results & Statistics]\n O --> P[Display Optimization Summary]\n \n style A fill:#4CAF50,stroke:#388E3C\n style P fill:#2196F3,stroke:#1976D2",
+ "name": "Optimization Execution Workflow"
}
]
}
@@ -356,7 +694,7 @@ Code analysis results from preprocessing phase, including definitions of functio
{
"code_dossier": {
"code_purpose": "entry",
- "description": "Project execution entry point for the cortex-mem-cli application. Parses CLI arguments, initializes tracing and configuration, creates the memory manager, and dispatches commands.",
+ "description": "Project execution entry point for Cortex Memory CLI. Parses CLI arguments, initializes the memory system, and routes commands to appropriate handlers.",
"file_path": "cortex-mem-cli/src/main.rs",
"functions": [
"main",
@@ -373,17 +711,17 @@ Code analysis results from preprocessing phase, including definitions of functio
"OptimizeCommandRunner"
],
"name": "main.rs",
- "source_summary": "use clap::{Parser, Subcommand};\nuse cortex_mem_core::{\n config::Config,\n initialize_memory_system,\n memory::MemoryManager,\n};\nuse std::path::PathBuf;\nuse std::sync::Arc;\nuse tokio;\nuse tracing::info;\nuse tracing_subscriber;\n\nmod commands;\n\nuse commands::{\n OptimizeCommand, \n OptimizationStatusCommand, \n OptimizationConfigCommand, \n OptimizeCommandRunner,\n};\nuse commands::add::AddCommand;\nuse commands::delete::DeleteCommand;\nuse commands::list::ListCommand;\nuse commands::search::SearchCommand;\n\n#[derive(Parser)]\n#[command(name = \"cortex-mem-cli\")]\n#[command(about = \"Rust Agent Memory System CLI\")]\npub struct Cli {\n #[command(subcommand)]\n pub command: Commands,\n\n /// Path to the configuration file\n #[arg(short, long, default_value = \"config.toml\")]\n pub config: PathBuf,\n}\n\n#[derive(Subcommand)]\npub enum Commands {\n /// Add a new memory\n Add {\n /// Content to store as memory\n #[arg(short, long)]\n content: String,\n /// User ID for the memory\n #[arg(short, long)]\n user_id: Option,\n /// Agent ID for the memory\n #[arg(short, long)]\n agent_id: Option,\n /// Memory type (conversational, procedural, factual)\n #[arg(short = 't', long, default_value = \"conversational\")]\n memory_type: String,\n },\n /// Search for memories\n Search {\n /// Search query (optional - if not provided, will use only metadata filters)\n #[arg(short, long)]\n query: Option,\n /// User ID filter\n #[arg(short, long)]\n user_id: Option,\n /// Agent ID filter\n #[arg(short, long)]\n agent_id: Option,\n /// Topics filter (comma-separated)\n #[arg(long, value_delimiter = ',')]\n topics: Option>,\n /// Keywords filter (comma-separated)\n #[arg(long, value_delimiter = ',')]\n keywords: Option>,\n /// Maximum number of results\n #[arg(short, long, default_value = \"10\")]\n limit: usize,\n },\n /// List memories\n List {\n /// User ID filter\n #[arg(short, long)]\n user_id: Option,\n /// Agent ID filter\n #[arg(short, long)]\n agent_id: Option,\n /// Memory type filter\n #[arg(short = 't', long)]\n memory_type: Option,\n /// Topics filter (comma-separated)\n #[arg(long, value_delimiter = ',')]\n topics: Option>,\n /// Keywords filter (comma-separated)\n #[arg(long, value_delimiter = ',')]\n keywords: Option>,\n /// Maximum number of results\n #[arg(short, long, default_value = \"20\")]\n limit: usize,\n },\n /// Delete a memory by ID\n Delete {\n /// Memory ID to delete\n id: String,\n },\n /// Optimize memory database\n Optimize {\n #[command(flatten)]\n cmd: OptimizeCommand,\n },\n /// Show optimization status\n OptimizeStatus {\n #[command(flatten)]\n cmd: OptimizationStatusCommand,\n },\n /// Manage optimization configuration\n OptimizeConfig {\n #[command(flatten)]\n cmd: OptimizationConfigCommand,\n },\n}\n\n#[tokio::main]\nasync fn main() -> Result<(), Box> {\n // Initialize tracing\n tracing_subscriber::fmt::init();\n\n let cli = Cli::parse();\n\n // Load configuration from file\n let config = Config::load(&cli.config)?;\n\n // Create memory manager\n let memory_manager = create_memory_manager(&config).await?;\n\n // Execute command\n match cli.command {\n Commands::Add {\n content,\n user_id,\n agent_id,\n memory_type,\n } => {\n let cmd = AddCommand::new(memory_manager);\n cmd.execute(content, user_id, agent_id, memory_type).await?;\n }\n Commands::Search {\n query,\n user_id,\n agent_id,\n topics,\n keywords,\n limit,\n } => {\n let cmd = SearchCommand::new(memory_manager);\n cmd.execute(query, user_id, agent_id, topics, keywords, limit).await?;\n }\n Commands::List {\n user_id,\n agent_id,\n memory_type,\n topics,\n keywords,\n limit,\n } => {\n let cmd = ListCommand::new(memory_manager);\n cmd.execute(user_id, agent_id, memory_type, topics, keywords, limit).await?;\n }\n Commands::Delete { id } => {\n let cmd = DeleteCommand::new(memory_manager);\n cmd.execute(id).await?;\n }\n Commands::Optimize { cmd } => {\n let runner = OptimizeCommandRunner::new(Arc::new(memory_manager), config);\n runner.run_optimize(&cmd).await?;\n }\n Commands::OptimizeStatus { cmd } => {\n let runner = OptimizeCommandRunner::new(Arc::new(memory_manager), config);\n runner.run_status(&cmd).await?;\n }\n Commands::OptimizeConfig { cmd } => {\n let runner = OptimizeCommandRunner::new(Arc::new(memory_manager), config);\n runner.run_config(&cmd).await?;\n }\n }\n\n Ok(())\n}\n\nasync fn create_memory_manager(\n config: &Config,\n) -> Result> {\n // Use the new initialization system with auto-detection\n let (vector_store, llm_client) = initialize_memory_system(config).await?;\n\n // Create memory manager\n let memory_manager = MemoryManager::new(vector_store, llm_client, config.memory.clone());\n\n info!(\"Memory manager initialized successfully with auto-detected embedding dimensions\");\n Ok(memory_manager)\n}\n"
+ "source_summary": "use clap::{Parser, Subcommand};\nuse cortex_mem_core::{\n config::Config,\n initialize_memory_system,\n memory::MemoryManager,\n};\nuse std::path::PathBuf;\nuse std::sync::Arc;\nuse tokio;\nuse tracing::info;\nuse tracing_subscriber;\n\nmod commands;\n\nuse commands::{\n OptimizeCommand,\n OptimizationStatusCommand,\n OptimizationConfigCommand,\n OptimizeCommandRunner,\n};\nuse commands::add::AddCommand;\nuse commands::delete::DeleteCommand;\nuse commands::list::ListCommand;\nuse commands::search::SearchCommand;\n\n#[derive(Parser)]\n#[command(name = \"cortex-mem-cli\")]\n#[command(about = \"Cortex Memory CLI for Agent Memory Layer\")]\n#[command(author = \"Sopaco\")]\n#[command(version)]\npub struct Cli {\n #[command(subcommand)]\n pub command: Commands,\n\n /// Path to the configuration file\n #[arg(short, long, default_value = \"config.toml\")]\n pub config: PathBuf,\n}\n\n#[derive(Subcommand)]\npub enum Commands {\n /// Add a new memory\n Add {\n /// Content to store as memory\n #[arg(short, long)]\n content: String,\n /// User ID for the memory\n #[arg(short, long)]\n user_id: Option,\n /// Agent ID for the memory\n #[arg(short, long)]\n agent_id: Option,\n /// Memory type (conversational, procedural, factual)\n #[arg(short = 't', long, default_value = \"conversational\")]\n memory_type: String,\n },\n /// Search for memories\n Search {\n /// Search query (optional - if not provided, will use only metadata filters)\n #[arg(short, long)]\n query: Option,\n /// User ID filter\n #[arg(short, long)]\n user_id: Option,\n /// Agent ID filter\n #[arg(short, long)]\n agent_id: Option,\n /// Topics filter (comma-separated)\n #[arg(long, value_delimiter = ',')]\n topics: Option>,\n /// Keywords filter (comma-separated)\n #[arg(long, value_delimiter = ',')]\n keywords: Option>,\n /// Maximum number of results\n #[arg(short, long, default_value = \"10\")]\n limit: usize,\n },\n /// List memories\n List {\n /// User ID filter\n #[arg(short, long)]\n user_id: Option,\n /// Agent ID filter\n #[arg(short, long)]\n agent_id: Option,\n /// Memory type filter\n #[arg(short = 't', long)]\n memory_type: Option,\n /// Topics filter (comma-separated)\n #[arg(long, value_delimiter = ',')]\n topics: Option>,\n /// Keywords filter (comma-separated)\n #[arg(long, value_delimiter = ',')]\n keywords: Option>,\n /// Maximum number of results\n #[arg(short, long, default_value = \"20\")]\n limit: usize,\n },\n /// Delete a memory by ID\n Delete {\n /// Memory ID to delete\n id: String,\n },\n /// Optimize memory database\n Optimize {\n #[command(flatten)]\n cmd: OptimizeCommand,\n },\n /// Show optimization status\n OptimizeStatus {\n #[command(flatten)]\n cmd: OptimizationStatusCommand,\n },\n /// Manage optimization configuration\n OptimizeConfig {\n #[command(flatten)]\n cmd: OptimizationConfigCommand,\n },\n}\n\n#[tokio::main]\nasync fn main() -> Result<(), Box> {\n // Initialize tracing\n tracing_subscriber::fmt::init();\n\n let cli = Cli::parse();\n\n // Load configuration from file\n let config = Config::load(&cli.config)?;\n\n // Create memory manager\n let memory_manager = create_memory_manager(&config).await?;\n\n // Execute command\n match cli.command {\n Commands::Add {\n content,\n user_id,\n agent_id,\n memory_type,\n } => {\n let cmd = AddCommand::new(memory_manager);\n cmd.execute(content, user_id, agent_id, memory_type).await?;\n }\n Commands::Search {\n query,\n user_id,\n agent_id,\n topics,\n keywords,\n limit,\n } => {\n let cmd = SearchCommand::new(memory_manager);\n cmd.execute(query, user_id, agent_id, topics, keywords, limit).await?;\n }\n Commands::List {\n user_id,\n agent_id,\n memory_type,\n topics,\n keywords,\n limit,\n } => {\n let cmd = ListCommand::new(memory_manager);\n cmd.execute(user_id, agent_id, memory_type, topics, keywords, limit).await?;\n }\n Commands::Delete { id } => {\n let cmd = DeleteCommand::new(memory_manager);\n cmd.execute(id).await?;\n }\n Commands::Optimize { cmd } => {\n let runner = OptimizeCommandRunner::new(Arc::new(memory_manager), config);\n runner.run_optimize(&cmd).await?;\n }\n Commands::OptimizeStatus { cmd } => {\n let runner = OptimizeCommandRunner::new(Arc::new(memory_manager), config);\n runner.run_status(&cmd).await?;\n }\n Commands::OptimizeConfig { cmd } => {\n let runner = OptimizeCommandRunner::new(Arc::new(memory_manager), config);\n runner.run_config(&cmd).await?;\n }\n }\n\n Ok(())\n}\n\nasync fn create_memory_manager(\n config: &Config,\n) -> Result> {\n // Use the new initialization system with auto-detection\n let (vector_store, llm_client) = initialize_memory_system(config).await?;\n\n // Create memory manager\n let memory_manager = MemoryManager::new(vector_store, llm_client, config.memory.clone());\n\n info!(\"Memory manager initialized successfully with auto-detected embedding dimensions\");\n Ok(memory_manager)\n}\n"
},
"complexity_metrics": {
- "cyclomatic_complexity": 6.0,
- "lines_of_code": 197,
+ "cyclomatic_complexity": 7.0,
+ "lines_of_code": 199,
"number_of_classes": 2,
"number_of_functions": 2
},
"dependencies": [
{
- "dependency_type": "use",
+ "dependency_type": "library",
"is_external": true,
"line_number": 1,
"name": "clap",
@@ -391,101 +729,109 @@ Code analysis results from preprocessing phase, including definitions of functio
"version": null
},
{
- "dependency_type": "use",
- "is_external": true,
+ "dependency_type": "library",
+ "is_external": false,
"line_number": 2,
"name": "cortex_mem_core",
"path": null,
"version": null
},
{
- "dependency_type": "use",
+ "dependency_type": "std",
"is_external": false,
- "line_number": 4,
+ "line_number": 3,
"name": "std::path::PathBuf",
"path": null,
"version": null
},
{
- "dependency_type": "use",
+ "dependency_type": "std",
"is_external": false,
- "line_number": 5,
+ "line_number": 4,
"name": "std::sync::Arc",
"path": null,
"version": null
},
{
- "dependency_type": "use",
+ "dependency_type": "library",
"is_external": true,
- "line_number": 6,
+ "line_number": 5,
"name": "tokio",
"path": null,
"version": null
},
{
- "dependency_type": "use",
+ "dependency_type": "library",
"is_external": true,
- "line_number": 7,
+ "line_number": 6,
"name": "tracing",
"path": null,
"version": null
},
{
- "dependency_type": "use",
+ "dependency_type": "library",
"is_external": true,
- "line_number": 8,
+ "line_number": 7,
"name": "tracing_subscriber",
"path": null,
"version": null
},
{
- "dependency_type": "mod",
+ "dependency_type": "module",
"is_external": false,
- "line_number": 10,
+ "line_number": 9,
"name": "commands",
"path": null,
"version": null
},
{
- "dependency_type": "use",
+ "dependency_type": "module",
+ "is_external": false,
+ "line_number": 11,
+ "name": "commands::add::AddCommand",
+ "path": null,
+ "version": null
+ },
+ {
+ "dependency_type": "module",
"is_external": false,
"line_number": 12,
- "name": "commands::OptimizeCommand",
+ "name": "commands::delete::DeleteCommand",
"path": null,
"version": null
},
{
- "dependency_type": "use",
+ "dependency_type": "module",
"is_external": false,
- "line_number": 15,
- "name": "commands::OptimizeCommandRunner",
+ "line_number": 13,
+ "name": "commands::list::ListCommand",
"path": null,
"version": null
},
{
- "dependency_type": "use",
+ "dependency_type": "module",
"is_external": false,
- "line_number": 16,
- "name": "commands::add::AddCommand",
+ "line_number": 14,
+ "name": "commands::search::SearchCommand",
"path": null,
"version": null
}
],
- "detailed_description": "This component serves as the entry point for the cortex-mem-cli application, implementing a command-line interface for interacting with a memory management system. It uses clap for argument parsing, defining a comprehensive set of subcommands for adding, searching, listing, and deleting memories, as well as optimization-related operations. The main function initializes tracing with tracing_subscriber, parses command-line arguments, loads configuration from a file, creates a MemoryManager instance via the core library's initialization system, and then dispatches to the appropriate command handler based on the user's input. The create_memory_manager function orchestrates the initialization of the memory system by leveraging the initialize_memory_system function from the core library, which auto-detects vector store and LLM client configurations. The component follows a clean separation of concerns by delegating command implementation to separate modules (add, delete, list, search, optimize) while maintaining the command dispatching logic centrally. It uses async/await for all operations, indicating that the underlying memory operations are non-blocking and likely involve I/O operations such as database access or network calls to LLM services.",
+ "detailed_description": "This component serves as the entry point for the Cortex Memory CLI application. It uses the Clap library to define and parse command-line arguments and subcommands for managing agent memories. The CLI supports operations including adding, searching, listing, and deleting memories, as well as optimization-related functions (optimize, status, config). Upon startup, it initializes tracing for logging, loads configuration from a TOML file, and creates a MemoryManager instance using an auto-detected vector store and LLM client. The main function routes each command to its respective handler, which are implemented in separate modules. The create_memory_manager function abstracts the initialization logic, promoting clean separation between setup and execution. All command executions are asynchronous, leveraging Tokio for runtime management.",
"interfaces": [
{
- "description": "Main CLI argument structure that contains the command to execute and global options like config file path",
+ "description": "Top-level CLI argument parser containing global options and subcommands",
"interface_type": "struct",
"name": "Cli",
"parameters": [
{
- "description": "The subcommand to execute",
+ "description": "Subcommand to execute",
"is_optional": false,
"name": "command",
"param_type": "Commands"
},
{
- "description": "Path to the configuration file, defaults to config.toml",
+ "description": "Path to configuration file, defaulting to config.toml",
"is_optional": false,
"name": "config",
"param_type": "PathBuf"
@@ -495,7 +841,7 @@ Code analysis results from preprocessing phase, including definitions of functio
"visibility": "pub"
},
{
- "description": "Enumeration of all available subcommands in the CLI: Add, Search, List, Delete, Optimize, OptimizeStatus, OptimizeConfig",
+ "description": "Enumeration of all available CLI subcommands with their specific arguments",
"interface_type": "enum",
"name": "Commands",
"parameters": [],
@@ -503,7 +849,7 @@ Code analysis results from preprocessing phase, including definitions of functio
"visibility": "pub"
},
{
- "description": "Entry point of the application that initializes the system and dispatches commands",
+ "description": "Entry point of the application that orchestrates initialization and command execution",
"interface_type": "function",
"name": "main",
"parameters": [],
@@ -512,17 +858,17 @@ Code analysis results from preprocessing phase, including definitions of functio
}
],
"responsibilities": [
- "Parse command-line arguments and subcommands using clap",
- "Initialize application logging and tracing infrastructure",
- "Load configuration from external files and pass to system components",
- "Create and manage the lifecycle of the MemoryManager instance",
- "Dispatch parsed commands to appropriate command handlers"
+ "Parse and validate command-line arguments using Clap",
+ "Initialize application logging and configuration subsystems",
+ "Bootstrap the memory management system with auto-detected components",
+ "Route CLI commands to their respective handler implementations",
+ "Manage lifecycle of asynchronous operations through Tokio runtime"
]
},
{
"code_dossier": {
"code_purpose": "entry",
- "description": "Entry point for the Cortex Memo MCP (Memory Control Protocol) server. Parses command-line arguments, initializes logging, constructs the MemoryMcpService with configuration, and serves it over stdio transport.",
+ "description": "Project execution entry point for Cortex Memory MCP Server, responsible for initializing configuration, logging, and starting the MCP service via stdio transport.",
"file_path": "cortex-mem-mcp/src/main.rs",
"functions": [
"main"
@@ -533,11 +879,11 @@ Code analysis results from preprocessing phase, including definitions of functio
"main"
],
"name": "main.rs",
- "source_summary": "use anyhow::anyhow;\nuse clap::Parser;\nuse cortex_mem_mcp::MemoryMcpService;\nuse rmcp::{transport::stdio, ServiceExt};\nuse std::path::PathBuf;\nuse tracing::{error, info};\n\n#[derive(Parser)]\n#[command(name = \"cortex-mem-mcp\")]\n#[command(about = \"MCP server for Cortex Memo memory management system\")]\nstruct Cli {\n /// Path to the configuration file\n #[arg(short, long, default_value = \"config.toml\")]\n config: PathBuf,\n\n /// Agent identifier for memory operations\n #[arg(long)]\n agent: Option,\n}\n\n#[tokio::main]\nasync fn main() -> Result<(), Box> {\n let cli = Cli::parse();\n\n // Initialize logging\n tracing_subscriber::fmt()\n .with_max_level(tracing::Level::INFO)\n .init();\n\n info!(\"Starting Cortex Memo MCP Server\");\n info!(\"Using configuration file: {:?}\", cli.config);\n\n // Create the service\n let service = MemoryMcpService::with_config_path_and_agent(cli.config, cli.agent)\n .await\n .map_err(|e| anyhow!(\"Failed to initialize memory management service: {}\", e))?;\n\n // Serve the MCP service\n let running_service = service\n .serve(stdio())\n .await\n .map_err(|e| anyhow!(\"Failed to start MCP server: {}\", e))?;\n\n info!(\"MCP server initialized successfully\");\n\n // Wait for the server to finish\n match running_service.waiting().await {\n Ok(reason) => info!(\"Server shutdown: {:?}\", reason),\n Err(e) => error!(\"Server error: {:?}\", e),\n }\n\n Ok(())\n}\n"
+ "source_summary": "use anyhow::anyhow;\nuse clap::Parser;\nuse cortex_mem_mcp::MemoryMcpService;\nuse rmcp::{transport::stdio, ServiceExt};\nuse std::path::PathBuf;\nuse tracing::{error, info};\n\n#[derive(Parser)]\n#[command(name = \"cortex-mem-mcp\")]\n#[command(about = \"MCP server of Cortex Memory to enhance agent's memory layer\")]\n#[command(author = \"Sopaco\")]\n#[command(version)]\nstruct Cli {\n /// Path to the configuration file\n #[arg(short, long, default_value = \"config.toml\")]\n config: PathBuf,\n\n /// Agent identifier for memory operations\n #[arg(long)]\n agent: Option,\n}\n\n#[tokio::main]\nasync fn main() -> Result<(), Box> {\n let cli = Cli::parse();\n\n // Initialize logging\n tracing_subscriber::fmt()\n .with_max_level(tracing::Level::INFO)\n .init();\n\n info!(\"Starting Cortex Memo MCP Server\");\n info!(\"Using configuration file: {:?}\", cli.config);\n\n // Create the service\n let service = MemoryMcpService::with_config_path_and_agent(cli.config, cli.agent)\n .await\n .map_err(|e| anyhow!(\"Failed to initialize memory management service: {}\", e))?;\n\n // Serve the MCP service\n let running_service = service\n .serve(stdio())\n .await\n .map_err(|e| anyhow!(\"Failed to start MCP server: {}\", e))?;\n\n info!(\"MCP server initialized successfully\");\n\n // Wait for the server to finish\n match running_service.waiting().await {\n Ok(reason) => info!(\"Server shutdown: {:?}\", reason),\n Err(e) => error!(\"Server error: {:?}\", e),\n }\n\n Ok(())\n}\n"
},
"complexity_metrics": {
- "cyclomatic_complexity": 5.0,
- "lines_of_code": 53,
+ "cyclomatic_complexity": 4.0,
+ "lines_of_code": 55,
"number_of_classes": 1,
"number_of_functions": 1
},
@@ -567,19 +913,19 @@ Code analysis results from preprocessing phase, including definitions of functio
"version": null
},
{
- "dependency_type": "protocol framework",
+ "dependency_type": "mcp framework",
"is_external": true,
"line_number": 4,
"name": "rmcp",
- "path": "rmcp::transport::stdio",
+ "path": "rmcp::{transport::stdio, ServiceExt}",
"version": null
},
{
"dependency_type": "standard library",
"is_external": false,
"line_number": 5,
- "name": "std",
- "path": "std::path::PathBuf",
+ "name": "std::path::PathBuf",
+ "path": null,
"version": null
},
{
@@ -589,28 +935,33 @@ Code analysis results from preprocessing phase, including definitions of functio
"name": "tracing",
"path": null,
"version": null
- },
- {
- "dependency_type": "async runtime",
- "is_external": true,
- "line_number": 19,
- "name": "tokio",
- "path": null,
- "version": null
}
],
- "detailed_description": "The main.rs file serves as the entry point for the Cortex Memo MCP server application. It utilizes the `clap` library for parsing command-line arguments, defining options for a configuration file path and an optional agent identifier. The `tracing` and `tracing_subscriber` crates are used to set up structured logging with an INFO level default. The core logic involves parsing the CLI arguments, initializing the logging system, creating an instance of `MemoryMcpService` by providing the configuration path and agent ID, and then serving this service using the `rmcp` framework's stdio transport. The server runs asynchronously using the `tokio` runtime, and the main function waits for the server to terminate, logging the reason for shutdown, whether it was a clean stop or an error.",
+ "detailed_description": "The main.rs file serves as the entry point for the Cortex Memory MCP (Memory Control Protocol) server. It uses Clap for command-line argument parsing, allowing users to specify a configuration file path and an optional agent identifier. The component initializes tracing-based logging with INFO level, constructs a MemoryMcpService instance using the provided configuration and agent ID, and then serves this service over stdio transport using the rmcp framework. Once the server is running, it awaits termination, logging shutdown reasons or errors accordingly. This module acts as a bootstrap for the entire memory enhancement service for AI agents, orchestrating setup and execution flow without containing business logic itself.",
"interfaces": [
{
- "description": "Command-line interface argument parser defined using clap. It configures the binary name and description, and specifies two arguments: a config file path (with a default) and an optional agent identifier.",
+ "description": "Command-line interface argument parser defining configuration file path and optional agent identifier",
"interface_type": "struct",
"name": "Cli",
- "parameters": [],
+ "parameters": [
+ {
+ "description": "Path to the TOML configuration file, defaults to 'config.toml'",
+ "is_optional": false,
+ "name": "config",
+ "param_type": "PathBuf"
+ },
+ {
+ "description": "Optional agent identifier used for scoping memory operations",
+ "is_optional": true,
+ "name": "agent",
+ "param_type": "Option"
+ }
+ ],
"return_type": null,
"visibility": "private"
},
{
- "description": "The asynchronous entry point of the application. It orchestrates the startup sequence: argument parsing, logging setup, service creation, server execution, and shutdown handling.",
+ "description": "Asynchronous entry point that parses CLI args, initializes logging, creates and runs the MCP service",
"interface_type": "function",
"name": "main",
"parameters": [],
@@ -619,11 +970,11 @@ Code analysis results from preprocessing phase, including definitions of functio
}
],
"responsibilities": [
- "Parse command-line arguments for configuration and agent settings.",
- "Initialize the application-wide structured logging system.",
- "Construct the core MemoryMcpService with provided configuration.",
- "Serve the MCP service over stdio and manage its lifecycle.",
- "Handle startup and runtime errors with appropriate logging."
+ "Parse command-line arguments for configuration and agent identification",
+ "Initialize structured logging with appropriate verbosity",
+ "Bootstrap and configure the MemoryMcpService with provided settings",
+ "Start and run the MCP server using stdio as transport mechanism",
+ "Handle server lifecycle events including graceful shutdown and error reporting"
]
},
{
@@ -712,105 +1063,133 @@ Code analysis results from preprocessing phase, including definitions of functio
{
"code_dossier": {
"code_purpose": "entry",
- "description": "Project execution entry point for demonstrating memory operations using shared MemoryOperations abstraction.",
- "file_path": "examples/memory-tools-refactor/src/main.rs",
+ "description": "Internationalization (i18n) module responsible for managing language settings, translations, and formatting across the application.",
+ "file_path": "cortex-mem-insights/src/lib/i18n/index.ts",
"functions": [
- "main"
+ "setLanguage",
+ "getCurrentLanguage",
+ "t",
+ "format.importance",
+ "format.quality",
+ "format.percentage",
+ "format.date",
+ "format.relativeTime"
],
"importance_score": 1.0,
"interfaces": [
- "main"
+ "Language",
+ "TranslationKey"
],
- "name": "main.rs",
- "source_summary": "use cortex_mem_config::Config;\nuse cortex_mem_core::{\n init::initialize_memory_system,\n memory::MemoryManager,\n};\nuse cortex_mem_tools::{MemoryOperations, MemoryOperationPayload};\nuse serde_json::json;\nuse std::sync::Arc;\nuse tracing::{info, Level};\nuse tracing_subscriber;\n\n#[tokio::main]\nasync fn main() -> Result<(), Box> {\n // Initialize logging\n tracing_subscriber::fmt()\n .with_max_level(Level::INFO)\n .init();\n\n info!(\"Starting memory tools refactor example\");\n\n // Load configuration\n let config = Config::load(\"config.toml\")?;\n info!(\"Loaded configuration\");\n\n // Initialize memory system\n let (vector_store, llm_client) = initialize_memory_system(&config).await?;\n info!(\"Initialized memory system\");\n\n // Create memory manager\n let memory_manager = Arc::new(MemoryManager::new(\n vector_store,\n llm_client,\n config.memory.clone(),\n ));\n info!(\"Created memory manager\");\n\n // Create shared operations\n let operations = MemoryOperations::new(\n memory_manager.clone(),\n Some(\"default_user\".to_string()),\n Some(\"default_agent\".to_string()),\n 10,\n );\n info!(\"Created shared operations\");\n\n // Test 1: Store a memory using the shared operations\n info!(\"Test 1: Storing a memory\");\n let mut store_payload = MemoryOperationPayload::default();\n store_payload.content = Some(\"This is a test memory for the shared operations demo\".to_string());\n store_payload.memory_type = Some(\"conversational\".to_string());\n store_payload.topics = Some(vec![\"testing\".to_string(), \"demo\".to_string()]);\n\n let store_result = operations.store_memory(store_payload).await?;\n info!(\"Store result: {}\", store_result.success);\n\n // Extract memory_id for use in later tests\n let memory_id = if let Some(data) = store_result.data {\n data.get(\"memory_id\").and_then(|v| v.as_str()).unwrap()\n } else {\n \"\"\n };\n\n // Test 2: Query memories using the shared operations\n info!(\"Test 2: Querying memories\");\n let mut query_payload = MemoryOperationPayload::default();\n query_payload.query = Some(\"test memory\".to_string());\n query_payload.limit = Some(5);\n\n let query_result = operations.query_memory(query_payload).await?;\n info!(\"Query result: {} (found {} memories)\",\n query_result.success,\n query_result.data\n .as_ref()\n .and_then(|d| d.get(\"count\"))\n .and_then(|c| c.as_u64())\n .unwrap_or(0));\n\n // Test 3: List memories using the shared operations\n info!(\"Test 3: Listing memories\");\n let mut list_payload = MemoryOperationPayload::default();\n list_payload.limit = Some(10);\n\n let list_result = operations.list_memories(list_payload).await?;\n info!(\"List result: {} (found {} memories)\",\n list_result.success,\n list_result.data\n .as_ref()\n .and_then(|d| d.get(\"count\"))\n .and_then(|c| c.as_u64())\n .unwrap_or(0));\n\n // Test 4: Get a specific memory using the shared operations\n if !memory_id.is_empty() {\n info!(\"Test 4: Getting specific memory\");\n let mut get_payload = MemoryOperationPayload::default();\n get_payload.memory_id = Some(memory_id.to_string());\n\n let get_result = operations.get_memory(get_payload).await?;\n info!(\"Get result: {}\", get_result.success);\n }\n\n info!(\"Memory tools refactor example completed successfully\");\n Ok(())\n}\n"
+ "name": "index.ts",
+ "source_summary": "import { writable, derived } from 'svelte/store';\nimport en from './locales/en.json';\nimport zh from './locales/zh.json';\nimport ja from './locales/ja.json';\n\nexport type Language = 'en' | 'zh' | 'ja';\nexport type TranslationKey = string;\n\nconst translations = {\n en,\n zh,\n ja\n};\n\n// 从localStorage获取保存的语言设置，默认为英文\nconst storedLanguage = typeof window !== 'undefined' ? localStorage.getItem('cortex-mem-language') as Language : null;\nconst defaultLanguage: Language = storedLanguage && ['en', 'zh', 'ja'].includes(storedLanguage) ? storedLanguage : 'en';\n\n// 创建语言store\nexport const language = writable(defaultLanguage);\n\n// 创建翻译store\nexport const t = derived(language, ($language) => {\n const currentTranslations = translations[$language];\n \n // 创建翻译函数\n const translate = (key: TranslationKey, params?: Record): string => {\n // 支持嵌套key，如 'common.appName'\n const keys = key.split('.');\n let value: any = currentTranslations;\n \n for (const k of keys) {\n if (value && typeof value === 'object' && k in value) {\n value = value[k];\n } else {\n // 如果找不到翻译，回退到英文\n let fallbackValue: any = translations.en;\n for (const fallbackKey of keys) {\n if (fallbackValue && typeof fallbackValue === 'object' && fallbackKey in fallbackValue) {\n fallbackValue = fallbackValue[fallbackKey];\n } else {\n return key; // 如果英文也没有，返回key本身\n }\n }\n value = fallbackValue;\n break;\n }\n }\n \n // 如果找到了字符串值，处理参数替换\n if (typeof value === 'string' && params) {\n return Object.entries(params).reduce((str, [paramKey, paramValue]) => {\n return str.replace(new RegExp(`\\{${paramKey}\\}`, 'g'), String(paramValue));\n }, value);\n }\n \n return typeof value === 'string' ? value : key;\n };\n \n return translate;\n});\n\n// 切换语言函数\nexport function setLanguage(newLanguage: Language): void {\n language.set(newLanguage);\n if (typeof window !== 'undefined') {\n localStorage.setItem('cortex-mem-language', newLanguage);\n }\n}\n\n// 获取当前语言\nexport function getCurrentLanguage(): Language {\n let currentLang: Language = 'en';\n language.subscribe((lang) => {\n currentLang = lang;\n })();\n return currentLang;\n}\n\n// 获取语言选项\nexport const languageOptions = [\n { value: 'en', label: 'English' },\n { value: 'zh', label: '中文' },\n { value: 'ja', label: '日本語' }\n];\n\n// 格式化函数：用于格式化数字、日期等\nexport const format = {\n // 格式化重要性分数（保留两位小数）\n importance: (value: number): string => {\n return value.toFixed(2);\n },\n \n // 格式化质量分数（保留两位小数）\n quality: (value: number): string => {\n return value.toFixed(2);\n },\n \n // 格式化百分比（用于进度条等）\n percentage: (value: number): string => {\n return `${(value * 100).toFixed(1)}%`;\n },\n \n // 格式化日期\n date: (dateString: string, locale?: string): string => {\n try {\n const date = new Date(dateString);\n const currentLocale = locale || getCurrentLanguage();\n const localeMap = {\n en: 'en-US',\n zh: 'zh-CN',\n ja: 'ja-JP'\n };\n return date.toLocaleString(localeMap[currentLocale] || 'en-US', {\n year: 'numeric',\n month: '2-digit',\n day: '2-digit',\n hour: '2-digit',\n minute: '2-digit',\n second: '2-digit'\n });\n } catch {\n return dateString;\n }\n },\n \n // 格式化相对时间\n relativeTime: (dateString: string): string => {\n try {\n const date = new Date(dateString);\n const now = new Date();\n const diffMs = now.getTime() - date.getTime();\n const diffMins = Math.floor(diffMs / 60000);\n const diffHours = Math.floor(diffMs / 3600000);\n const diffDays = Math.floor(diffMs / 86400000);\n \n if (diffMins < 1) return 'just now';\n if (diffMins < 60) return `${diffMins}m ago`;\n if (diffHours < 24) return `${diffHours}h ago`;\n if (diffDays < 7) return `${diffDays}d ago`;\n \n return format.date(dateString);\n } catch {\n return dateString;\n }\n }\n};"
},
"complexity_metrics": {
- "cyclomatic_complexity": 5.0,
- "lines_of_code": 104,
+ "cyclomatic_complexity": 11.0,
+ "lines_of_code": 147,
"number_of_classes": 0,
- "number_of_functions": 1
+ "number_of_functions": 8
},
"dependencies": [
{
- "dependency_type": "use",
- "is_external": false,
+ "dependency_type": "import",
+ "is_external": true,
"line_number": 1,
- "name": "cortex_mem_config",
- "path": "cortex_mem_config::Config",
+ "name": "svelte/store",
+ "path": "svelte/store",
"version": null
},
{
- "dependency_type": "use",
+ "dependency_type": "import",
"is_external": false,
"line_number": 2,
- "name": "cortex_mem_core",
- "path": "cortex_mem_core::{init::initialize_memory_system, memory::MemoryManager}",
+ "name": "./locales/en.json",
+ "path": "./locales/en.json",
"version": null
},
{
- "dependency_type": "use",
+ "dependency_type": "import",
"is_external": false,
- "line_number": 4,
- "name": "cortex_mem_tools",
- "path": "cortex_mem_tools::{MemoryOperations, MemoryOperationPayload}",
+ "line_number": 3,
+ "name": "./locales/zh.json",
+ "path": "./locales/zh.json",
"version": null
},
{
- "dependency_type": "use",
- "is_external": true,
- "line_number": 5,
- "name": "serde_json",
- "path": "serde_json::json",
+ "dependency_type": "import",
+ "is_external": false,
+ "line_number": 4,
+ "name": "./locales/ja.json",
+ "path": "./locales/ja.json",
"version": null
- },
+ }
+ ],
+ "detailed_description": "This component serves as the core internationalization (i18n) module for the application. It manages multi-language support by loading locale-specific translation files (en, zh, ja), persisting user language preferences via localStorage, and providing reactive translation and formatting utilities. The `t` function is a derived store that reacts to language changes and supports nested translation keys with parameter interpolation. A fallback mechanism ensures English is used when translations are missing. The `format` object provides reusable formatting methods for numbers, percentages, dates, and relative time, localized based on current language. Language state is managed using Svelte's writable and derived stores for reactivity. The module also exposes language options for UI selection and allows imperative language switching via `setLanguage`.",
+ "interfaces": [
{
- "dependency_type": "use",
- "is_external": true,
- "line_number": 7,
- "name": "tokio",
- "path": "tokio::main",
- "version": null
+ "description": "Represents the supported language codes in the application.",
+ "interface_type": "type",
+ "name": "Language",
+ "parameters": [],
+ "return_type": "'en' | 'zh' | 'ja'",
+ "visibility": "public"
},
{
- "dependency_type": "use",
- "is_external": true,
- "line_number": 6,
- "name": "tracing",
- "path": "tracing::{info, Level}",
- "version": null
+ "description": "Type alias for translation string keys, supporting dot notation for nesting.",
+ "interface_type": "type",
+ "name": "TranslationKey",
+ "parameters": [],
+ "return_type": "string",
+ "visibility": "public"
},
{
- "dependency_type": "use",
- "is_external": true,
- "line_number": 7,
- "name": "tracing_subscriber",
- "path": "tracing_subscriber",
- "version": null
- }
- ],
- "detailed_description": "This component serves as the entry point for a demonstration application showcasing the refactored memory tools system. It initializes the logging system using tracing_subscriber, loads configuration from a TOML file, sets up the core memory system via initialize_memory_system which returns a vector store and LLM client, and creates a MemoryManager wrapped in an Arc for shared ownership. It then instantiates a MemoryOperations struct providing a unified interface for memory manipulation with default user, agent, and batch size. The main logic consists of four sequential tests: storing a new memory with specific content, topics, and type; querying memories using a text search; listing all stored memories with a limit; and retrieving a specific memory by its ID obtained from the store result. Each operation logs its progress and outcome, concluding with a success message. The use of async/await indicates non-blocking operations, likely involving I/O such as database access or API calls.",
- "interfaces": [
+ "description": "Derived store that returns a translation function based on current language",
+ "interface_type": "store",
+ "name": "t",
+ "parameters": [
+ {
+ "description": "Dot-separated path to the translation string",
+ "is_optional": false,
+ "name": "key",
+ "param_type": "TranslationKey"
+ },
+ {
+ "description": "Optional parameters for interpolation in the translated string",
+ "is_optional": true,
+ "name": "params",
+ "param_type": "Record"
+ }
+ ],
+ "return_type": "string",
+ "visibility": "public"
+ },
{
- "description": "Asynchronous entry point that orchestrates the memory operations demo, returning Ok on success or a boxed error.",
+ "description": "Updates the current language and persists it to localStorage",
"interface_type": "function",
- "name": "main",
- "parameters": [],
- "return_type": "Result<(), Box>",
+ "name": "setLanguage",
+ "parameters": [
+ {
+ "description": "The language code to switch to",
+ "is_optional": false,
+ "name": "newLanguage",
+ "param_type": "Language"
+ }
+ ],
+ "return_type": "void",
"visibility": "public"
}
],
"responsibilities": [
- "Initialize the application runtime environment including logging and configuration",
- "Orchestrate the setup of core memory system components (vector store, LLM client, memory manager)",
- "Instantiate and manage the shared MemoryOperations interface for memory manipulation",
- "Execute end-to-end demonstration of memory operations (store, query, list, get)",
- "Handle errors gracefully and provide detailed execution logging"
+ "Manage application-wide language state using reactive stores",
+ "Provide translation lookup with fallback to English and support for nested keys and parameter interpolation",
+ "Persist and retrieve user language preference via localStorage",
+ "Expose a set of formatting utilities for numbers, dates, and relative time with localization",
+ "Provide language selection options for UI components"
]
},
{
"code_dossier": {
"code_purpose": "entry",
- "description": "Main application entry point for a memory-enabled agent system with TUI interface and background memory persistence.",
+ "description": "Main application entry point for Cortex Memory TARS, a terminal-based interactive AI assistant with memory capabilities. Handles initialization, event loop, UI rendering and shutdown sequence.",
"file_path": "examples/cortex-mem-tars/src/main.rs",
"functions": [
"main",
@@ -825,16 +1204,15 @@ Code analysis results from preprocessing phase, including definitions of functio
"Cli",
"AppMessage",
"App",
- "MemoryManager",
- "OpenAILLMClient",
- "QdrantVectorStore"
+ "draw_ui",
+ "handle_key_event"
],
"name": "main.rs",
- "source_summary": "use clap::Parser;\nuse crossterm::{\n event, execute,\n terminal::{EnterAlternateScreen, enable_raw_mode},\n};\nuse cortex_mem_config::Config;\nuse cortex_mem_core::init_logging;\nuse cortex_mem_rig::{\n llm::OpenAILLMClient, memory::manager::MemoryManager, vector_store::qdrant::QdrantVectorStore,\n};\nuse ratatui::{Terminal, backend::CrosstermBackend};\nuse std::{io, path::PathBuf, sync::Arc};\nuse tokio::sync::mpsc;\nuse tokio::time::Duration;\n\nmod agent;\nmod app;\nmod events;\nmod log_monitor;\nmod terminal;\nmod ui;\n\nuse agent::{\n agent_reply_with_memory_retrieval_streaming, create_memory_agent, extract_user_basic_info,\n store_conversations_batch,\n};\nuse app::{App, AppMessage, redirect_log_to_ui, set_global_log_sender};\nuse events::{handle_key_event, process_user_input};\nuse log_monitor::start_log_monitoring_task;\nuse terminal::cleanup_terminal_final;\nuse ui::draw_ui;\n\n#[derive(Parser)]\n#[command(name = \"multi-round-interactive\")]\n#[command(about = \"Multi-round interactive conversation with a memory-enabled agent\")]\nstruct Cli {\n /// Path to the configuration file\n #[arg(short, long, default_value = \"config.toml\")]\n config: PathBuf,\n}\n\n#[tokio::main]\nasync fn main() -> Result<(), Box> {\n // 加载基本配置以获取日志设置\n let cli = Cli::parse();\n let config = Config::load(&cli.config)?;\n\n // 初始化日志系统\n init_logging(&config.logging)?;\n\n // 设置终端\n enable_raw_mode()?;\n let mut stdout = io::stdout();\n execute!(\n stdout,\n EnterAlternateScreen,\n crossterm::event::EnableMouseCapture\n )?;\n let backend = CrosstermBackend::new(stdout);\n let mut terminal = Terminal::new(backend)?;\n\n let result = run_application(&mut terminal).await;\n\n // 最终清理 - 使用最彻底的方法\n cleanup_terminal_final(&mut terminal);\n\n result\n}\n\n/// 主应用逻辑\nasync fn run_application(\n terminal: &mut Terminal>,\n) -> Result<(), Box> {\n // 创建消息通道\n let (msg_tx, mut msg_rx) = mpsc::unbounded_channel::();\n\n // 使用我们的自定义日志系统，禁用tracing\n // tracing_subscriber::fmt::init();\n\n // 设置全局日志发送器以便我们的日志系统正常工作\n set_global_log_sender(msg_tx.clone());\n\n // 初始化组件\n // 配置加载已经在main函数中完成，这里只获取文件路径\n let cli = Cli::parse();\n let config = Config::load(&cli.config)?;\n\n let llm_client = OpenAILLMClient::new(&config.llm, &config.embedding)?;\n let vector_store = QdrantVectorStore::new(&config.qdrant)\n .await\n .expect(\"无法连接到Qdrant\");\n\n let memory_config = config.memory.clone();\n let memory_manager = Arc::new(MemoryManager::new(\n Box::new(vector_store),\n Box::new(llm_client.clone()),\n memory_config,\n ));\n\n // 创建带记忆的Agent\n let memory_tool_config = cortex_mem_rig::tool::MemoryToolConfig {\n default_user_id: Some(\"demo_user\".to_string()),\n ..Default::default()\n };\n\n let agent = create_memory_agent(memory_manager.clone(), memory_tool_config, &config).await?;\n\n // 初始化用户信息\n let user_id = \"demo_user\";\n let user_info = extract_user_basic_info(&config, memory_manager.clone(), user_id).await?;\n\n // 创建应用状态\n let mut app = App::new(msg_tx);\n\n if let Some(info) = user_info {\n app.user_info = Some(info.clone());\n app.log_info(\"已加载用户基本信息\");\n } else {\n app.log_info(\"未找到用户基本信息\");\n }\n\n app.log_info(\"初始化完成，开始对话...\");\n\n // 主事件循环\n loop {\n // 更新消息（包括在quit过程中收到的所有消息）\n while let Ok(msg) = msg_rx.try_recv() {\n match msg {\n AppMessage::Log(log_msg) => {\n app.add_log(log_msg);\n }\n AppMessage::Conversation { user, assistant } => {\n app.add_conversation(user, assistant);\n }\n AppMessage::StreamingChunk { user, chunk } => {\n // 如果是新的用户输入，开始新的流式回复\n if app.current_streaming_response.is_none() || \n app.current_streaming_response.as_ref().map(|(u, _)| u != &user).unwrap_or(false) {\n app.start_streaming_response(user);\n }\n app.add_streaming_chunk(chunk);\n }\n AppMessage::StreamingComplete { user: _, full_response: _ } => {\n app.complete_streaming_response();\n }\n AppMessage::MemoryIterationCompleted => {\n app.memory_iteration_completed = true;\n app.should_quit = true;\n }\n }\n }\n\n // 绘制UI\n terminal.draw(|f| draw_ui(f, &mut app))?;\n\n // 处理事件\n if event::poll(std::time::Duration::from_millis(100))? {\n if let Some(input) = handle_key_event(event::read()?, &mut app) {\n // 先检查是否是quit命令\n let is_quit = process_user_input(input.clone(), &mut app);\n\n // 如果是quit命令，先添加到对话历史\n if is_quit {\n app.add_conversation(input.clone(), \"正在执行退出命令...\".to_string());\n }\n\n if is_quit {\n // 立即退出到terminal，后台执行记忆化任务\n let conversations_vec: Vec<(String, String)> =\n app.conversations.iter().map(|(user, assistant, _)| (user.clone(), assistant.clone())).collect();\n handle_quit_async(\n terminal,\n &mut app,\n &conversations_vec,\n &memory_manager,\n user_id,\n )\n .await?;\n\n // 退出主循环\n break;\n } else {\n // 记录用户输入\n redirect_log_to_ui(\"INFO\", &format!(\"接收用户输入: {}\", input));\n\n // 处理用户输入\n let agent_clone = agent.clone();\n let memory_manager_clone = memory_manager.clone();\n let config_clone = config.clone();\n let user_info_clone = app.user_info.clone();\n let user_id_clone = user_id.to_string();\n let msg_tx_clone = app.message_sender.clone();\n\n // 获取当前对话历史的引用（转换为slice）\n let current_conversations: Vec<(String, String)> =\n app.conversations.iter().map(|(user, assistant, _)| (user.clone(), assistant.clone())).collect();\n\n // 记录开始处理\n redirect_log_to_ui(\"INFO\", \"开始处理用户请求...\");\n\n tokio::spawn(async move {\n // 创建流式通道\n let (stream_tx, mut stream_rx) = mpsc::unbounded_channel::();\n \n // 启动流式处理任务\n let agent_clone2 = agent_clone.clone();\n let memory_manager_clone2 = memory_manager_clone.clone();\n let config_clone2 = config_clone.clone();\n let user_info_clone2 = user_info_clone.clone();\n let user_id_clone2 = user_id_clone.clone();\n let input_clone = input.clone();\n let current_conversations_clone = current_conversations.clone();\n \n let generation_task = tokio::spawn(async move {\n agent_reply_with_memory_retrieval_streaming(\n &agent_clone2,\n memory_manager_clone2,\n &input_clone,\n &user_id_clone2,\n user_info_clone2.as_deref(),\n ¤t_conversations_clone,\n stream_tx,\n )\n .await\n });\n\n // 处理流式内容\n while let Some(chunk) = stream_rx.recv().await {\n if let Some(sender) = &msg_tx_clone {\n let _ = sender.send(AppMessage::StreamingChunk {\n user: input.clone(),\n chunk,\n });\n }\n }\n\n // 等待生成任务完成\n match generation_task.await {\n Ok(Ok(full_response)) => {\n // 发送完成消息\n if let Some(sender) = &msg_tx_clone {\n let _ = sender.send(AppMessage::StreamingComplete {\n user: input.clone(),\n full_response: full_response.clone(),\n });\n redirect_log_to_ui(\"INFO\", &format!(\"生成回复完成: {}\", full_response));\n }\n }\n Ok(Err(e)) => {\n let error_msg = format!(\"抱歉，我遇到了一些技术问题: {}\", e);\n redirect_log_to_ui(\"ERROR\", &error_msg);\n // 完成流式回复（即使出错也要清理状态）\n if let Some(sender) = &msg_tx_clone {\n let _ = sender.send(AppMessage::StreamingComplete {\n user: input.clone(),\n full_response: error_msg,\n });\n }\n }\n Err(e) => {\n let error_msg = format!(\"任务执行失败: {}\", e);\n redirect_log_to_ui(\"ERROR\", &error_msg);\n // 完成流式回复（即使出错也要清理状态）\n if let Some(sender) = &msg_tx_clone {\n let _ = sender.send(AppMessage::StreamingComplete {\n user: input.clone(),\n full_response: error_msg,\n });\n }\n }\n }\n });\n }\n }\n }\n\n // 检查是否有新的对话结果\n app.is_processing = false;\n\n // 只有在没有在shutting down状态或者记忆化已完成时才能退出\n if app.should_quit && app.memory_iteration_completed {\n break;\n }\n\n // **在quit过程中处理剩余的日志消息但不退出**\n if app.is_shutting_down && !app.memory_iteration_completed {\n // **立即处理所有待处理的日志消息**\n while let Ok(msg) = msg_rx.try_recv() {\n match msg {\n AppMessage::Log(log_msg) => {\n app.add_log(log_msg);\n }\n AppMessage::Conversation { user, assistant } => {\n app.add_conversation(user, assistant);\n }\n AppMessage::StreamingChunk { user, chunk } => {\n // 如果是新的用户输入，开始新的流式回复\n if app.current_streaming_response.is_none() || \n app.current_streaming_response.as_ref().map(|(u, _)| u != &user).unwrap_or(false) {\n app.start_streaming_response(user);\n }\n app.add_streaming_chunk(chunk);\n }\n AppMessage::StreamingComplete { user: _, full_response: _ } => {\n app.complete_streaming_response();\n }\n AppMessage::MemoryIterationCompleted => {\n app.memory_iteration_completed = true;\n app.should_quit = true;\n break;\n }\n }\n }\n\n // 在shutting down期间立即刷新UI显示最新日志\n if let Err(e) = terminal.draw(|f| draw_ui(f, &mut app)) {\n eprintln!(\"UI绘制错误: {}\", e);\n }\n\n // 在shutting down期间添加短暂延迟，让用户能看到日志更新\n tokio::time::sleep(tokio::time::Duration::from_millis(50)).await;\n }\n }\n\n println!(\"Cortex TARS powering down. Goodbye!\");\n Ok(())\n}\n\n/// 异步处理退出逻辑，立即退出TUI到terminal\nasync fn handle_quit_async(\n _terminal: &mut Terminal>,\n app: &mut App,\n conversations: &Vec<(String, String)>,\n memory_manager: &Arc,\n user_id: &str,\n) -> Result<(), Box> {\n use crossterm::cursor::{MoveTo, Show};\n use crossterm::style::{\n Attribute, Color, ResetColor, SetAttribute, SetBackgroundColor, SetForegroundColor,\n };\n use crossterm::{\n event::DisableMouseCapture,\n execute,\n terminal::{Clear, ClearType, LeaveAlternateScreen},\n };\n use std::io::{Write, stdout};\n\n // 记录退出命令到UI\n redirect_log_to_ui(\"INFO\", \"🚀 用户输入退出命令 /quit，开始后台记忆化...\");\n\n // 先获取所有日志内容\n let all_logs: Vec = app.logs.iter().cloned().collect();\n\n // 彻底清理terminal状态\n let mut stdout = stdout();\n\n // 执行完整的terminal重置序列\n execute!(&mut stdout, ResetColor)?;\n execute!(&mut stdout, Clear(ClearType::All))?;\n execute!(&mut stdout, MoveTo(0, 0))?;\n execute!(&mut stdout, Show)?;\n execute!(&mut stdout, LeaveAlternateScreen)?;\n execute!(&mut stdout, DisableMouseCapture)?;\n execute!(&mut stdout, SetAttribute(Attribute::Reset))?;\n execute!(&mut stdout, SetForegroundColor(Color::Reset))?;\n execute!(&mut stdout, SetBackgroundColor(Color::Reset))?;\n\n // 禁用原始模式\n let _ = crossterm::terminal::disable_raw_mode();\n\n // 刷新输出确保清理完成\n stdout.flush()?;\n\n // 输出分隔线\n println!(\"\\n╔══════════════════════════════════════════════════════════════════════════════╗\");\n println!(\"║ 🧠 Cortex Memory - 退出流程 ║\");\n println!(\"╚══════════════════════════════════════════════════════════════════════════════╝\");\n\n // 显示会话摘要\n println!(\"📋 会话摘要:\");\n println!(\" • 对话轮次: {} 轮\", conversations.len());\n println!(\" • 用户ID: {}\", user_id);\n\n // 显示最近的日志（如果有）\n if !all_logs.is_empty() {\n println!(\"\\n📜 最近的操作日志:\");\n let recent_logs = if all_logs.len() > 10 {\n &all_logs[all_logs.len() - 10..]\n } else {\n &all_logs[..]\n };\n\n println!(\" {}\", \"─\".repeat(70));\n for (i, log) in recent_logs.iter().enumerate() {\n let beautified_content = beautify_log_content(log);\n\n // 添加日志条目编号\n if i > 0 {\n println!(\" {}\", \"─\".repeat(70));\n }\n\n // 显示美化后的内容，支持多行显示\n let lines: Vec<&str> = beautified_content.split('\\n').collect();\n for (line_i, line) in lines.iter().enumerate() {\n if line_i == 0 {\n // 第一行显示编号和完整内容\n let colored_line = get_log_level_color(log, line);\n println!(\" {}\", colored_line);\n } else {\n // 后续行添加缩进\n println!(\" │ {}\", line);\n }\n }\n }\n if all_logs.len() > 10 {\n println!(\" {}\", \"─\".repeat(70));\n println!(\" ... (显示最近10条，共{}条)\", all_logs.len());\n }\n }\n\n println!(\"\\n🧠 开始执行记忆化存储...\");\n\n // 准备对话数据（过滤quit命令）\n let mut valid_conversations = Vec::new();\n for (user_msg, assistant_msg) in conversations {\n let user_msg_trimmed = user_msg.trim().to_lowercase();\n if user_msg_trimmed == \"quit\"\n || user_msg_trimmed == \"exit\"\n || user_msg_trimmed == \"/quit\"\n || user_msg_trimmed == \"/exit\"\n {\n continue;\n }\n valid_conversations.push((user_msg.clone(), assistant_msg.clone()));\n }\n\n if valid_conversations.is_empty() {\n println!(\"⚠️ 没有需要存储的内容\");\n println!(\n \"\\n╔══════════════════════════════════════════════════════════════════════════════╗\"\n );\n println!(\n \"║ ✅ 退出流程完成 ║\"\n );\n println!(\n \"╚══════════════════════════════════════════════════════════════════════════════╝\"\n );\n println!(\"👋 感谢使用Cortex Memory！\");\n return Ok(());\n }\n\n // 只有在有内容需要存储时才启动日志监听任务\n let log_dir = \"logs\".to_string();\n let log_monitoring_handle = tokio::spawn(async move {\n if let Err(e) = start_log_monitoring_task(log_dir).await {\n eprintln!(\"日志监听任务失败: {}\", e);\n }\n });\n\n println!(\n \"📝 正在保存 {} 条对话记录到记忆库...\",\n valid_conversations.len()\n );\n println!(\"🚀 开始存储对话到记忆系统...\");\n\n // 执行批量记忆化\n match store_conversations_batch(memory_manager.clone(), &valid_conversations, user_id).await {\n Ok(_) => {\n println!(\"✨ 记忆化完成！\");\n println!(\"✅ 所有对话已成功存储到记忆系统\");\n println!(\"🔍 存储详情:\");\n println!(\" • 对话轮次: {} 轮\", valid_conversations.len());\n println!(\" • 用户消息: {} 条\", valid_conversations.len());\n println!(\" • 助手消息: {} 条\", valid_conversations.len());\n }\n Err(e) => {\n println!(\"❌ 记忆存储失败: {}\", e);\n println!(\"⚠️ 虽然记忆化失败，但仍正常退出\");\n }\n }\n\n // 停止日志监听任务\n log_monitoring_handle.abort();\n\n tokio::time::sleep(Duration::from_secs(3)).await;\n\n println!(\"\\n╔══════════════════════════════════════════════════════════════════════════════╗\");\n println!(\"║ 🎉 退出流程完成 ║\");\n println!(\"╚══════════════════════════════════════════════════════════════════════════════╝\");\n println!(\"👋 感谢使用Cortex Memory！\");\n\n Ok(())\n}\n\n/// 美化日志内容显示\nfn beautify_log_content(log_line: &str) -> String {\n // 过滤掉时间戳前缀，保持简洁\n let content = if let Some(content_start) = log_line.find(\"] \") {\n &log_line[content_start + 2..]\n } else {\n log_line\n };\n\n // 判断是否为JSON内容\n let trimmed_content = content.trim();\n let is_json = trimmed_content.starts_with('{') && trimmed_content.ends_with('}');\n\n if is_json {\n // 尝试美化JSON，保留完整内容\n match prettify_json(trimmed_content) {\n Ok(formatted_json) => {\n // 如果格式化成功，返回完整的带缩进的JSON\n formatted_json\n }\n Err(_) => {\n // 如果JSON格式化失败，返回原始内容\n content.to_string()\n }\n }\n } else {\n // 非JSON内容，保持原样\n content.to_string()\n }\n}\n\n/// 美化JSON内容\nfn prettify_json(json_str: &str) -> Result> {\n use serde_json::Value;\n\n let value: Value = serde_json::from_str(json_str)?;\n Ok(serde_json::to_string_pretty(&value)?)\n}\n\n/// 根据日志级别返回带颜色的文本\nfn get_log_level_color(log_line: &str, text: &str) -> String {\n let log_level = if let Some(level_start) = log_line.find(\"[\") {\n if let Some(level_end) = log_line[level_start..].find(\"]\") {\n &log_line[level_start + 1..level_start + level_end]\n } else {\n \"UNKNOWN\"\n }\n } else {\n \"UNKNOWN\"\n };\n\n // ANSI颜色代码\n let (color_code, reset_code) = match log_level.to_uppercase().as_str() {\n \"ERROR\" => (\"\\x1b[91m\", \"\\x1b[0m\"), // 亮红色\n \"WARN\" | \"WARNING\" => (\"\\x1b[93m\", \"\\x1b[0m\"), // 亮黄色\n \"INFO\" => (\"\\x1b[36m\", \"\\x1b[0m\"), // 亮青色\n \"DEBUG\" => (\"\\x1b[94m\", \"\\x1b[0m\"), // 亮蓝色\n \"TRACE\" => (\"\\x1b[95m\", \"\\x1b[0m\"), // 亮紫色\n _ => (\"\\x1b[0m\", \"\\x1b[0m\"), // 白色\n };\n\n format!(\"{}{}{}\", color_code, text, reset_code)\n}\n"
+ "source_summary": "use clap::Parser;\nuse crossterm::{\n event, execute,\n terminal::{EnterAlternateScreen, enable_raw_mode},\n};\nuse cortex_mem_config::Config;\nuse cortex_mem_core::init_logging;\nuse cortex_mem_rig::{\n llm::OpenAILLMClient, memory::manager::MemoryManager, vector_store::qdrant::QdrantVectorStore,\n};\nuse ratatui::{Terminal, backend::CrosstermBackend};\nuse std::{io, path::PathBuf, sync::Arc};\nuse tokio::sync::mpsc;\nuse tokio::time::Duration;\n\nmod agent;\nmod app;\nmod events;\nmod log_monitor;\nmod terminal;\nmod ui;\n\nuse agent::{\n agent_reply_with_memory_retrieval_streaming, create_memory_agent, extract_user_basic_info,\n store_conversations_batch,\n};\nuse app::{App, AppMessage, redirect_log_to_ui, set_global_log_sender};\nuse events::{handle_key_event, process_user_input};\nuse log_monitor::start_log_monitoring_task;\nuse terminal::cleanup_terminal_final;\nuse ui::draw_ui;\n\n#[derive(Parser)]\n#[command(name = \"Cortex Memory Tars\")]\n#[command(about = \"A Multi-round interactive conversation with a memory-enabled agent\")]\n#[command(author = \"Sopaco\")]\n#[command(version)]\nstruct Cli {\n /// Path to the configuration file\n #[arg(short, long, default_value = \"config.toml\")]\n config: PathBuf,\n}\n\n#[tokio::main]\nasync fn main() -> Result<(), Box> {\n // 加载基本配置以获取日志设置\n let cli = Cli::parse();\n let config = Config::load(&cli.config)?;\n\n // 初始化日志系统\n init_logging(&config.logging)?;\n\n // 设置终端\n enable_raw_mode()?;\n let mut stdout = io::stdout();\n execute!(\n stdout,\n EnterAlternateScreen,\n crossterm::event::EnableMouseCapture\n )?;\n let backend = CrosstermBackend::new(stdout);\n let mut terminal = Terminal::new(backend)?;\n\n let result = run_application(&mut terminal).await;\n\n // 最终清理 - 使用最彻底的方法\n cleanup_terminal_final(&mut terminal);\n\n result\n}\n\n/// 主应用逻辑\nasync fn run_application(\n terminal: &mut Terminal>,\n) -> Result<(), Box> {\n // 创建消息通道\n let (msg_tx, mut msg_rx) = mpsc::unbounded_channel::();\n\n // 使用我们的自定义日志系统，禁用tracing\n // tracing_subscriber::fmt::init();\n\n // 设置全局日志发送器以便我们的日志系统正常工作\n set_global_log_sender(msg_tx.clone());\n\n // 初始化组件\n // 配置加载已经在main函数中完成，这里只获取文件路径\n let cli = Cli::parse();\n let config = Config::load(&cli.config)?;\n\n let llm_client = OpenAILLMClient::new(&config.llm, &config.embedding)?;\n let vector_store = QdrantVectorStore::new(&config.qdrant)\n .await\n .expect(\"无法连接到Qdrant\");\n\n let memory_config = config.memory.clone();\n let memory_manager = Arc::new(MemoryManager::new(\n Box::new(vector_store),\n Box::new(llm_client.clone()),\n memory_config,\n ));\n\n // 创建带记忆的Agent\n let memory_tool_config = cortex_mem_rig::tool::MemoryToolConfig {\n default_user_id: Some(\"demo_user\".to_string()),\n ..Default::default()\n };\n\n let agent = create_memory_agent(memory_manager.clone(), memory_tool_config, &config).await?;\n\n // 初始化用户信息\n let user_id = \"demo_user\";\n let user_info = extract_user_basic_info(&config, memory_manager.clone(), user_id).await?;\n\n // 创建应用状态\n let mut app = App::new(msg_tx);\n\n if let Some(info) = user_info {\n app.user_info = Some(info.clone());\n app.log_info(\"已加载用户基本信息\");\n } else {\n app.log_info(\"未找到用户基本信息\");\n }\n\n app.log_info(\"初始化完成，开始对话...\");\n\n // 主事件循环\n loop {\n // 更新消息（包括在quit过程中收到的所有消息）\n while let Ok(msg) = msg_rx.try_recv() {\n match msg {\n AppMessage::Log(log_msg) => {\n app.add_log(log_msg);\n }\n AppMessage::Conversation { user, assistant } => {\n app.add_conversation(user, assistant);\n }\n AppMessage::StreamingChunk { user, chunk } => {\n // 如果是新的用户输入，开始新的流式回复\n if app.current_streaming_response.is_none() ||\n app.current_streaming_response.as_ref().map(|(u, _)| u != &user).unwrap_or(false) {\n app.start_streaming_response(user);\n }\n app.add_streaming_chunk(chunk);\n }\n AppMessage::StreamingComplete { user: _, full_response: _ } => {\n app.complete_streaming_response();\n }\n AppMessage::MemoryIterationCompleted => {\n app.memory_iteration_completed = true;\n app.should_quit = true;\n }\n }\n }\n\n // 绘制UI\n terminal.draw(|f| draw_ui(f, &mut app))?;\n\n // 处理事件\n if event::poll(std::time::Duration::from_millis(100))? {\n if let Some(input) = handle_key_event(event::read()?, &mut app) {\n // 先检查是否是quit命令\n let is_quit = process_user_input(input.clone(), &mut app);\n\n // 如果是quit命令，先添加到对话历史\n if is_quit {\n app.add_conversation(input.clone(), \"正在执行退出命令...\".to_string());\n }\n\n if is_quit {\n // 立即退出到terminal，后台执行记忆化任务\n let conversations_vec: Vec<(String, String)> =\n app.conversations.iter().map(|(user, assistant, _)| (user.clone(), assistant.clone())).collect();\n handle_quit_async(\n terminal,\n &mut app,\n &conversations_vec,\n &memory_manager,\n user_id,\n )\n .await?;\n\n // 退出主循环\n break;\n } else {\n // 记录用户输入\n redirect_log_to_ui(\"INFO\", &format!(\"接收用户输入: {}\", input));\n\n // 处理用户输入\n let agent_clone = agent.clone();\n let memory_manager_clone = memory_manager.clone();\n let config_clone = config.clone();\n let user_info_clone = app.user_info.clone();\n let user_id_clone = user_id.to_string();\n let msg_tx_clone = app.message_sender.clone();\n\n // 获取当前对话历史的引用（转换为slice）\n let current_conversations: Vec<(String, String)> =\n app.conversations.iter().map(|(user, assistant, _)| (user.clone(), assistant.clone())).collect();\n\n // 记录开始处理\n redirect_log_to_ui(\"INFO\", \"开始处理用户请求...\");\n\n tokio::spawn(async move {\n // 创建流式通道\n let (stream_tx, mut stream_rx) = mpsc::unbounded_channel::();\n\n // 启动流式处理任务\n let agent_clone2 = agent_clone.clone();\n let memory_manager_clone2 = memory_manager_clone.clone();\n let config_clone2 = config_clone.clone();\n let user_info_clone2 = user_info_clone.clone();\n let user_id_clone2 = user_id_clone.clone();\n let input_clone = input.clone();\n let current_conversations_clone = current_conversations.clone();\n\n let generation_task = tokio::spawn(async move {\n agent_reply_with_memory_retrieval_streaming(\n &agent_clone2,\n memory_manager_clone2,\n &input_clone,\n &user_id_clone2,\n user_info_clone2.as_deref(),\n ¤t_conversations_clone,\n stream_tx,\n )\n .await\n });\n\n // 处理流式内容\n while let Some(chunk) = stream_rx.recv().await {\n if let Some(sender) = &msg_tx_clone {\n let _ = sender.send(AppMessage::StreamingChunk {\n user: input.clone(),\n chunk,\n });\n }\n }\n\n // 等待生成任务完成\n match generation_task.await {\n Ok(Ok(full_response)) => {\n // 发送完成消息\n if let Some(sender) = &msg_tx_clone {\n let _ = sender.send(AppMessage::StreamingComplete {\n user: input.clone(),\n full_response: full_response.clone(),\n });\n redirect_log_to_ui(\"INFO\", &format!(\"生成回复完成: {}\", full_response));\n }\n }\n Ok(Err(e)) => {\n let error_msg = format!(\"抱歉，我遇到了一些技术问题: {}\", e);\n redirect_log_to_ui(\"ERROR\", &error_msg);\n // 完成流式回复（即使出错也要清理状态）\n if let Some(sender) = &msg_tx_clone {\n let _ = sender.send(AppMessage::StreamingComplete {\n user: input.clone(),\n full_response: error_msg,\n });\n }\n }\n Err(e) => {\n let error_msg = format!(\"任务执行失败: {}\", e);\n redirect_log_to_ui(\"ERROR\", &error_msg);\n // 完成流式回复（即使出错也要清理状态）\n if let Some(sender) = &msg_tx_clone {\n let _ = sender.send(AppMessage::StreamingComplete {\n user: input.clone(),\n full_response: error_msg,\n });\n }\n }\n }\n });\n }\n }\n }\n\n // 检查是否有新的对话结果\n app.is_processing = false;\n\n // 只有在没有在shutting down状态或者记忆化已完成时才能退出\n if app.should_quit && app.memory_iteration_completed {\n break;\n }\n\n // **在quit过程中处理剩余的日志消息但不退出**\n if app.is_shutting_down && !app.memory_iteration_completed {\n // **立即处理所有待处理的日志消息**\n while let Ok(msg) = msg_rx.try_recv() {\n match msg {\n AppMessage::Log(log_msg) => {\n app.add_log(log_msg);\n }\n AppMessage::Conversation { user, assistant } => {\n app.add_conversation(user, assistant);\n }\n AppMessage::StreamingChunk { user, chunk } => {\n // 如果是新的用户输入，开始新的流式回复\n if app.current_streaming_response.is_none() ||\n app.current_streaming_response.as_ref().map(|(u, _)| u != &user).unwrap_or(false) {\n app.start_streaming_response(user);\n }\n app.add_streaming_chunk(chunk);\n }\n AppMessage::StreamingComplete { user: _, full_response: _ } => {\n app.complete_streaming_response();\n }\n AppMessage::MemoryIterationCompleted => {\n app.memory_iteration_completed = true;\n app.should_quit = true;\n break;\n }\n }\n }\n\n // 在shutting down期间立即刷新UI显示最新日志\n if let Err(e) = terminal.draw(|f| draw_ui(f, &mut app)) {\n eprintln!(\"UI绘制错误: {}\", e);\n }\n\n // 在shutting down期间添加短暂延迟，让用户能看到日志更新\n tokio::time::sleep(tokio::time::Duration::from_millis(50)).await;\n }\n }\n\n println!(\"Cortex TARS powering down. Goodbye!\");\n Ok(())\n}\n\n/// 异步处理退出逻辑，立即退出TUI到terminal\nasync fn handle_quit_async(\n _terminal: &mut Terminal>,\n app: &mut App,\n conversations: &Vec<(String, String)>,\n memory_manager: &Arc,\n user_id: &str,\n) -> Result<(), Box> {\n use crossterm::cursor::{MoveTo, Show};\n use crossterm::style::{\n Attribute, Color, ResetColor, SetAttribute, SetBackgroundColor, SetForegroundColor,\n };\n use crossterm::{\n event::DisableMouseCapture,\n execute,\n terminal::{Clear, ClearType, LeaveAlternateScreen},\n };\n use std::io::{Write, stdout};\n\n // 记录退出命令到UI\n redirect_log_to_ui(\"INFO\", \"🚀 用户输入退出命令 /quit，开始后台记忆化...\");\n\n // 先获取所有日志内容\n let all_logs: Vec = app.logs.iter().cloned().collect();\n\n // 彻底清理terminal状态\n let mut stdout = stdout();\n\n // 执行完整的terminal重置序列\n execute!(&mut stdout, ResetColor)?;\n execute!(&mut stdout, Clear(ClearType::All))?;\n execute!(&mut stdout, MoveTo(0, 0))?;\n execute!(&mut stdout, Show)?;\n execute!(&mut stdout, LeaveAlternateScreen)?;\n execute!(&mut stdout, DisableMouseCapture)?;\n execute!(&mut stdout, SetAttribute(Attribute::Reset))?;\n execute!(&mut stdout, SetForegroundColor(Color::Reset))?;\n execute!(&mut stdout, SetBackgroundColor(Color::Reset))?;\n\n // 禁用原始模式\n let _ = crossterm::terminal::disable_raw_mode();\n\n // 刷新输出确保清理完成\n stdout.flush()?;\n\n // 输出分隔线\n println!(\"\\n╔══════════════════════════════════════════════════════════════════════════════╗\");\n println!(\"║ 🧠 Cortex Memory - 退出流程 ║\");\n println!(\"╚══════════════════════════════════════════════════════════════════════════════╝\");\n\n // 显示会话摘要\n println!(\"📋 会话摘要:\");\n println!(\" • 对话轮次: {} 轮\", conversations.len());\n println!(\" • 用户ID: {}\", user_id);\n\n // 显示最近的日志（如果有）\n if !all_logs.is_empty() {\n println!(\"\\n📜 最近的操作日志:\");\n let recent_logs = if all_logs.len() > 10 {\n &all_logs[all_logs.len() - 10..]\n } else {\n &all_logs[..]\n };\n\n println!(\" {}\", \"─\".repeat(70));\n for (i, log) in recent_logs.iter().enumerate() {\n let beautified_content = beautify_log_content(log);\n\n // 添加日志条目编号\n if i > 0 {\n println!(\" {}\", \"─\".repeat(70));\n }\n\n // 显示美化后的内容，支持多行显示\n let lines: Vec<&str> = beautified_content.split('\\n').collect();\n for (line_i, line) in lines.iter().enumerate() {\n if line_i == 0 {\n // 第一行显示编号和完整内容\n let colored_line = get_log_level_color(log, line);\n println!(\" {}\", colored_line);\n } else {\n // 后续行添加缩进\n println!(\" │ {}\", line);\n }\n }\n }\n if all_logs.len() > 10 {\n println!(\" {}\", \"─\".repeat(70));\n println!(\" ... (显示最近10条，共{}条)\", all_logs.len());\n }\n }\n\n println!(\"\\n🧠 开始执行记忆化存储...\");\n\n // 准备对话数据（过滤quit命令）\n let mut valid_conversations = Vec::new();\n for (user_msg, assistant_msg) in conversations {\n let user_msg_trimmed = user_msg.trim().to_lowercase();\n if user_msg_trimmed == \"quit\"\n || user_msg_trimmed == \"exit\"\n || user_msg_trimmed == \"/quit\"\n || user_msg_trimmed == \"/exit\"\n {\n continue;\n }\n valid_conversations.push((user_msg.clone(), assistant_msg.clone()));\n }\n\n if valid_conversations.is_empty() {\n println!(\"⚠️ 没有需要存储的内容\");\n println!(\n \"\\n╔══════════════════════════════════════════════════════════════════════════════╗\"\n );\n println!(\n \"║ ✅ 退出流程完成 ║\"\n );\n println!(\n \"╚══════════════════════════════════════════════════════════════════════════════╝\"\n );\n println!(\"👋 感谢使用Cortex Memory！\");\n return Ok(());\n }\n\n // 只有在有内容需要存储时才启动日志监听任务\n let log_dir = \"logs\".to_string();\n let log_monitoring_handle = tokio::spawn(async move {\n if let Err(e) = start_log_monitoring_task(log_dir).await {\n eprintln!(\"日志监听任务失败: {}\", e);\n }\n });\n\n println!(\n \"📝 正在保存 {} 条对话记录到记忆库...\",\n valid_conversations.len()\n );\n println!(\"🚀 开始存储对话到记忆系统...\");\n\n // 执行批量记忆化\n match store_conversations_batch(memory_manager.clone(), &valid_conversations, user_id).await {\n Ok(_) => {\n println!(\"✨ 记忆化完成！\");\n println!(\"✅ 所有对话已成功存储到记忆系统\");\n println!(\"🔍 存储详情:\");\n println!(\" • 对话轮次: {} 轮\", valid_conversations.len());\n println!(\" • 用户消息: {} 条\", valid_conversations.len());\n println!(\" • 助手消息: {} 条\", valid_conversations.len());\n }\n Err(e) => {\n println!(\"❌ 记忆存储失败: {}\", e);\n println!(\"⚠️ 虽然记忆化失败，但仍正常退出\");\n }\n }\n\n // 停止日志监听任务\n log_monitoring_handle.abort();\n\n tokio::time::sleep(Duration::from_secs(3)).await;\n\n println!(\"\\n╔══════════════════════════════════════════════════════════════════════════════╗\");\n println!(\"║ 🎉 退出流程完成 ║\");\n println!(\"╚══════════════════════════════════════════════════════════════════════════════╝\");\n println!(\"👋 感谢使用Cortex Memory！\");\n\n Ok(())\n}\n\n/// 美化日志内容显示\nfn beautify_log_content(log_line: &str) -> String {\n // 过滤掉时间戳前缀，保持简洁\n let content = if let Some(content_start) = log_line.find(\"] \") {\n &log_line[content_start + 2..]\n } else {\n log_line\n };\n\n // 判断是否为JSON内容\n let trimmed_content = content.trim();\n let is_json = trimmed_content.starts_with('{') && trimmed_content.ends_with('}');\n\n if is_json {\n // 尝试美化JSON，保留完整内容\n match prettify_json(trimmed_content) {\n Ok(formatted_json) => {\n // 如果格式化成功，返回完整的带缩进的JSON\n formatted_json\n }\n Err(_) => {\n // 如果JSON格式化失败，返回原始内容\n content.to_string()\n }\n }\n } else {\n // 非JSON内容，保持原样\n content.to_string()\n }\n}\n\n/// 美化JSON内容\nfn prettify_json(json_str: &str) -> Result> {\n use serde_json::Value;\n\n let value: Value = serde_json::from_str(json_str)?;\n Ok(serde_json::to_string_pretty(&value)?)\n}\n\n/// 根据日志级别返回带颜色的文本\nfn get_log_level_color(log_line: &str, text: &str) -> String {\n let log_level = if let Some(level_start) = log_line.find(\"[\") {\n if let Some(level_end) = log_line[level_start..].find(\"]\") {\n &log_line[level_start + 1..level_start + level_end]\n } else {\n \"UNKNOWN\"\n }\n } else {\n \"UNKNOWN\"\n };\n\n // ANSI颜色代码\n let (color_code, reset_code) = match log_level.to_uppercase().as_str() {\n \"ERROR\" => (\"\\x1b[91m\", \"\\x1b[0m\"), // 亮红色\n \"WARN\" | \"WARNING\" => (\"\\x1b[93m\", \"\\x1b[0m\"), // 亮黄色\n \"INFO\" => (\"\\x1b[36m\", \"\\x1b[0m\"), // 亮青色\n \"DEBUG\" => (\"\\x1b[94m\", \"\\x1b[0m\"), // 亮蓝色\n \"TRACE\" => (\"\\x1b[95m\", \"\\x1b[0m\"), // 亮紫色\n _ => (\"\\x1b[0m\", \"\\x1b[0m\"), // 白色\n };\n\n format!(\"{}{}{}\", color_code, text, reset_code)\n}\n"
},
"complexity_metrics": {
"cyclomatic_complexity": 39.0,
- "lines_of_code": 557,
+ "lines_of_code": 559,
"number_of_classes": 1,
"number_of_functions": 6
},
@@ -887,6 +1265,14 @@ Code analysis results from preprocessing phase, including definitions of functio
"path": null,
"version": null
},
+ {
+ "dependency_type": "std",
+ "is_external": true,
+ "line_number": 9,
+ "name": "std",
+ "path": null,
+ "version": null
+ },
{
"dependency_type": "crate",
"is_external": true,
@@ -898,7 +1284,7 @@ Code analysis results from preprocessing phase, including definitions of functio
{
"dependency_type": "module",
"is_external": false,
- "line_number": 16,
+ "line_number": 20,
"name": "agent",
"path": "./examples/cortex-mem-tars/src/agent.rs",
"version": null
@@ -906,7 +1292,7 @@ Code analysis results from preprocessing phase, including definitions of functio
{
"dependency_type": "module",
"is_external": false,
- "line_number": 17,
+ "line_number": 21,
"name": "app",
"path": "./examples/cortex-mem-tars/src/app.rs",
"version": null
@@ -914,7 +1300,7 @@ Code analysis results from preprocessing phase, including definitions of functio
{
"dependency_type": "module",
"is_external": false,
- "line_number": 18,
+ "line_number": 22,
"name": "events",
"path": "./examples/cortex-mem-tars/src/events.rs",
"version": null
@@ -922,7 +1308,7 @@ Code analysis results from preprocessing phase, including definitions of functio
{
"dependency_type": "module",
"is_external": false,
- "line_number": 19,
+ "line_number": 23,
"name": "log_monitor",
"path": "./examples/cortex-mem-tars/src/log_monitor.rs",
"version": null
@@ -930,7 +1316,7 @@ Code analysis results from preprocessing phase, including definitions of functio
{
"dependency_type": "module",
"is_external": false,
- "line_number": 20,
+ "line_number": 24,
"name": "terminal",
"path": "./examples/cortex-mem-tars/src/terminal.rs",
"version": null
@@ -938,31 +1324,24 @@ Code analysis results from preprocessing phase, including definitions of functio
{
"dependency_type": "module",
"is_external": false,
- "line_number": 21,
+ "line_number": 25,
"name": "ui",
"path": "./examples/cortex-mem-tars/src/ui.rs",
"version": null
}
],
- "detailed_description": "This component serves as the main entry point for a sophisticated AI agent system with persistent memory capabilities. It implements a terminal-based user interface using ratatui and crossterm, enabling interactive conversations with an AI agent that can remember and retrieve past interactions. The system follows a clean architecture pattern with clear separation of concerns, where the main function orchestrates the initialization of all components, including configuration loading, logging setup, terminal configuration, and core system components like the LLM client and vector store. The application features a central event loop that handles user input, renders the UI, and manages asynchronous tasks through message passing via mpsc channels. A key architectural feature is the graceful shutdown process that allows the application to exit the TUI interface immediately while continuing to process memory persistence tasks in the background. The agent system uses a memory manager with Qdrant as a vector database to store and retrieve conversational context, enabling the AI to maintain continuity across sessions. The code demonstrates sophisticated error handling, resource cleanup, and user experience considerations like colored log output and session summaries during shutdown.",
+ "detailed_description": "This is the main application entry point for Cortex Memory TARS, a terminal-based interactive AI assistant with persistent memory capabilities. The component orchestrates the entire application lifecycle from initialization to shutdown. It integrates multiple subsystems including terminal UI (using ratatui and crossterm), logging, event handling, memory management, and AI agent interaction. The core functionality revolves around providing a continuous conversation interface where users can interact with an AI agent that maintains context across interactions through a memory system. The application features a sophisticated shutdown sequence that continues processing memory storage operations after the UI has been terminated, ensuring data persistence even during exit. Key technical aspects include async/await concurrency model, message passing between components via channels, and integration with external services like OpenAI and Qdrant vector database.",
"interfaces": [
{
"description": "Command line interface configuration with configuration file path parameter",
"interface_type": "struct",
"name": "Cli",
- "parameters": [
- {
- "description": "Path to configuration file, defaults to config.toml",
- "is_optional": false,
- "name": "config",
- "param_type": "PathBuf"
- }
- ],
+ "parameters": [],
"return_type": null,
"visibility": "public"
},
{
- "description": "Application entry point that initializes components and starts the main event loop",
+ "description": "Entry point of the application, initializes configuration, logging and terminal, then runs the main application loop",
"interface_type": "function",
"name": "main",
"parameters": [],
@@ -970,69 +1349,69 @@ Code analysis results from preprocessing phase, including definitions of functio
"visibility": "public"
},
{
- "description": "Main application loop that handles user input, UI rendering, and message processing",
+ "description": "Main application logic loop that handles events, updates state, and renders UI",
"interface_type": "function",
"name": "run_application",
"parameters": [
{
- "description": "Reference to the terminal for UI rendering",
+ "description": "Reference to the terminal instance for UI rendering",
"is_optional": false,
"name": "terminal",
- "param_type": "Terminal>"
+ "param_type": "&mut Terminal>"
}
],
"return_type": "Result<(), Box>",
"visibility": "private"
},
{
- "description": "Handles application shutdown with background memory persistence tasks",
+ "description": "Handles asynchronous shutdown sequence, including memory persistence operations",
"interface_type": "function",
"name": "handle_quit_async",
"parameters": [
{
- "description": "Terminal reference for cleanup",
+ "description": "Terminal reference (unused in function)",
"is_optional": false,
"name": "_terminal",
- "param_type": "Terminal>"
+ "param_type": "&mut Terminal>"
},
{
- "description": "Application state",
+ "description": "Mutable reference to application state",
"is_optional": false,
"name": "app",
- "param_type": "App"
+ "param_type": "&mut App"
},
{
- "description": "Conversation history to persist",
+ "description": "Reference to conversation history",
"is_optional": false,
"name": "conversations",
- "param_type": "Vec<(String, String)>"
+ "param_type": "&Vec<(String, String)>"
},
{
- "description": "Memory management system",
+ "description": "Reference to shared memory manager",
"is_optional": false,
"name": "memory_manager",
- "param_type": "Arc"
+ "param_type": "&Arc"
},
{
- "description": "User identifier for memory operations",
+ "description": "User identifier string",
"is_optional": false,
"name": "user_id",
- "param_type": "str"
+ "param_type": "&str"
}
],
"return_type": "Result<(), Box>",
"visibility": "private"
},
{
- "description": "Formats log content for display, with JSON pretty-printing support",
+ "description": "Processes log content for display, extracting meaningful content and formatting JSON",
"interface_type": "function",
"name": "beautify_log_content",
"parameters": [
{
- "description": "Raw log line to format",
+ "description": "Log line to beautify",
"is_optional": false,
"name": "log_line",
- "param_type": "str"
+ "param_type": "&str"
}
],
"return_type": "String",
@@ -1040,359 +1419,208 @@ Code analysis results from preprocessing phase, including definitions of functio
}
],
"responsibilities": [
- "Orchestrate application lifecycle including initialization and graceful shutdown",
- "Manage TUI interface with ratatui and handle user input events",
- "Coordinate message passing between UI, agent, and logging systems",
- "Implement background memory persistence during application exit",
- "Handle configuration loading and system component initialization"
+ "Initialize application components and dependencies",
+ "Manage application lifecycle from startup to shutdown",
+ "Orchestrate the main event loop for user interaction",
+ "Handle terminal UI rendering and input processing",
+ "Coordinate memory persistence operations during shutdown"
]
},
{
"code_dossier": {
"code_purpose": "entry",
- "description": "Cortex-Mem 核心能力评估框架的执行入口，支持多种评估模式和数据集管理",
- "file_path": "examples/cortex-mem-evaluation/src/main.rs",
+ "description": null,
+ "file_path": "cortex-mem-service/src/main.rs",
"functions": [
- "main"
+ "main",
+ "create_memory_manager"
],
"importance_score": 1.0,
"interfaces": [
+ "AppState",
"Cli",
- "Commands",
- "main"
+ "OptimizationJobState"
],
"name": "main.rs",
- "source_summary": "use anyhow::Result;\nuse clap::{Parser, Subcommand};\nuse std::path::PathBuf;\nuse tracing::info;\n\nmod evaluator;\nmod dataset;\nmod runner;\nmod report;\nmod memory;\n\nuse crate::runner::ExperimentRunner;\n\n/// Cortex-Mem 核心能力评估框架\n#[derive(Parser)]\n#[command(name = \"cortex-mem-evaluation\")]\n#[command(about = \"评估 Cortex-Mem 核心能力的框架\", long_about = None)]\nstruct Cli {\n #[command(subcommand)]\n command: Commands,\n}\n\n#[derive(Subcommand)]\nenum Commands {\n /// 运行完整评估\n Run {\n /// 配置文件路径\n #[arg(short, long, default_value = \"config/evaluation_config.toml\")]\n config: PathBuf,\n \n /// 输出目录\n #[arg(short, long, default_value = \"results\")]\n output_dir: PathBuf,\n },\n \n /// 仅运行召回率评估\n Recall {\n /// 配置文件路径\n #[arg(short, long, default_value = \"config/evaluation_config.toml\")]\n config: PathBuf,\n \n /// 输出目录\n #[arg(short, long, default_value = \"results\")]\n output_dir: PathBuf,\n },\n \n /// 仅运行有效性评估\n Effectiveness {\n /// 配置文件路径\n #[arg(short, long, default_value = \"config/evaluation_config.toml\")]\n config: PathBuf,\n \n /// 输出目录\n #[arg(short, long, default_value = \"results\")]\n output_dir: PathBuf,\n },\n \n /// 仅运行性能评估\n Performance {\n /// 配置文件路径\n #[arg(short, long, default_value = \"config/evaluation_config.toml\")]\n config: PathBuf,\n \n /// 输出目录\n #[arg(short, long, default_value = \"results\")]\n output_dir: PathBuf,\n },\n \n /// 生成测试数据集\n GenerateDataset {\n /// 数据集类型：recall, effectiveness, all\n #[arg(short, long, default_value = \"all\")]\n dataset_type: String,\n \n /// 输出目录\n #[arg(short, long, default_value = \"data\")]\n output_dir: PathBuf,\n \n /// 数据集大小\n #[arg(short, long, default_value = \"100\")]\n size: usize,\n \n /// 是否使用实验室数据\n #[arg(long, default_value = \"true\")]\n use_lab_data: bool,\n },\n \n /// 验证测试数据集\n ValidateDataset {\n /// 数据集路径\n #[arg(short, long)]\n dataset_path: PathBuf,\n \n /// 数据集类型：recall, effectiveness\n #[arg(short, long)]\n dataset_type: String,\n },\n}\n\n#[tokio::main]\nasync fn main() -> Result<()> {\n // 初始化日志\n tracing_subscriber::fmt()\n .with_max_level(tracing::Level::INFO)\n .with_target(false)\n .init();\n \n let cli = Cli::parse();\n \n match cli.command {\n Commands::Run { config, output_dir } => {\n info!(\"开始运行完整评估...\");\n let runner = ExperimentRunner::new(config, output_dir)?;\n runner.run_full_evaluation().await?;\n info!(\"评估完成！\");\n }\n \n Commands::Recall { config, output_dir } => {\n info!(\"开始运行召回率评估...\");\n let runner = ExperimentRunner::new(config, output_dir)?;\n runner.run_recall_evaluation().await?;\n info!(\"召回率评估完成！\");\n }\n \n Commands::Effectiveness { config, output_dir } => {\n info!(\"开始运行有效性评估...\");\n let runner = ExperimentRunner::new(config, output_dir)?;\n runner.run_effectiveness_evaluation().await?;\n info!(\"有效性评估完成！\");\n }\n \n Commands::Performance { config, output_dir } => {\n info!(\"开始运行性能评估...\");\n let runner = ExperimentRunner::new(config, output_dir)?;\n runner.run_full_evaluation().await?;\n info!(\"性能评估完成！\");\n }\n \n Commands::GenerateDataset { dataset_type, output_dir, size, use_lab_data } => {\n info!(\"开始生成测试数据集...\");\n crate::dataset::generate_test_dataset(&dataset_type, &output_dir, size, use_lab_data).await?;\n info!(\"测试数据集生成完成！\");\n }\n \n Commands::ValidateDataset { dataset_path, dataset_type } => {\n info!(\"开始验证测试数据集...\");\n crate::dataset::validate_dataset(&dataset_path, &dataset_type).await?;\n info!(\"测试数据集验证完成！\");\n }\n }\n \n Ok(())\n}"
+ "source_summary": "use axum::{\n Router,\n routing::{get, post},\n};\nuse clap::Parser;\nuse cortex_mem_core::{\n config::Config, llm::create_llm_client, memory::MemoryManager,\n vector_store::qdrant::QdrantVectorStore,\n};\nuse std::{path::PathBuf, sync::Arc};\nuse tokio::net::TcpListener;\nuse tower::ServiceBuilder;\nuse tower_http::cors::CorsLayer;\nuse tracing::info;\nuse tracing_subscriber;\n\nmod handlers;\nmod models;\nmod optimization_handlers;\n\nuse handlers::{\n\n batch_delete_memories, batch_update_memories, create_memory, delete_memory, get_memory, health_check, list_memories, search_memories, update_memory, get_llm_status, llm_health_check,\n\n};\nuse optimization_handlers::{\n analyze_optimization, cancel_optimization, cleanup_history, get_optimization_history,\n get_optimization_statistics, get_optimization_status, start_optimization,\n OptimizationJobState,\n};\n\n/// Application state shared across handlers\n#[derive(Clone)]\npub struct AppState {\n pub memory_manager: Arc,\n pub optimization_jobs: Arc>>,\n}\n\n#[derive(Parser)]\n#[command(name = \"cortex-mem-service\")]\n#[command(about = \"Cortex Memory HTTP Service\")]\n#[command(author = \"Sopaco\")]\n#[command(version)]\nstruct Cli {\n /// Path to the configuration file\n #[arg(short, long, default_value = \"config.toml\")]\n config: PathBuf,\n}\n\n#[tokio::main]\nasync fn main() -> Result<(), Box> {\n // Initialize tracing\n tracing_subscriber::fmt::init();\n\n let cli = Cli::parse();\n\n // Load configuration\n let config = Config::load(&cli.config)?;\n\n // Create memory manager\n let memory_manager = create_memory_manager(&config).await?;\n\n // Create application state\n let app_state = AppState {\n memory_manager: Arc::new(memory_manager),\n optimization_jobs: Arc::new(tokio::sync::RwLock::new(std::collections::HashMap::new())),\n };\n\n // Build the application router\n let app = Router::new()\n .route(\"/health\", get(health_check))\n .route(\"/memories\", post(create_memory).get(list_memories))\n .route(\"/memories/search\", post(search_memories))\n .route(\n \"/memories/{id}\",\n get(get_memory).put(update_memory).delete(delete_memory),\n )\n .route(\"/memories/batch/delete\", post(batch_delete_memories))\n .route(\"/memories/batch/update\", post(batch_update_memories))\n // Optimization routes\n .route(\"/optimization\", post(start_optimization))\n .route(\"/optimization/{job_id}\", get(get_optimization_status))\n .route(\"/optimization/{job_id}/cancel\", post(cancel_optimization))\n .route(\"/optimization/history\", get(get_optimization_history))\n .route(\"/optimization/analyze\", post(analyze_optimization))\n .route(\"/optimization/statistics\", get(get_optimization_statistics))\n .route(\"/optimization/cleanup\", post(cleanup_history))\n // LLM service status routes\n .route(\"/llm/status\", get(get_llm_status))\n .route(\"/llm/health-check\", get(llm_health_check))\n .layer(\n ServiceBuilder::new()\n .layer(CorsLayer::permissive())\n .into_inner(),\n )\n .with_state(app_state);\n\n // Start the server\n let addr = format!(\"{}:{}\", config.server.host, config.server.port);\n\n info!(\"Starting cortex-mem-service on {}\", addr);\n\n let listener = TcpListener::bind(&addr).await?;\n axum::serve(listener, app).await?;\n\n Ok(())\n}\n\nasync fn create_memory_manager(\n config: &Config,\n) -> Result
+
