Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
Feature/new demo (#78)
Allend101fac8ec1a
diff --git a/examples/memex/.gitignore b/examples/memex/.gitignorenew file mode 100644index 000000000..bda059da6--- /dev/null+++ b/examples/memex/.gitignore@@ -0,0 +1,7 @@+.venv/+__pycache__/+*.pyc+.pytest_cache/+data/+uv.lock+ov.confdiff --git a/examples/memex/README.md b/examples/memex/README.mdnew file mode 100644index 000000000..6814752cb--- /dev/null+++ b/examples/memex/README.md@@ -0,0 +1,210 @@+# Memex - Personal Knowledge Assistant++A CLI-based personal knowledge assistant powered by OpenViking.++## Features++- **Knowledge Management**: Add files, directories, URLs to your knowledge base+- **Intelligent Q&A**: RAG-based question answering with multi-turn conversation+- **Session Memory**: Automatic memory extraction and context-aware search via OpenViking Session+- **Knowledge Browsing**: Navigate with L0/L1/L2 context layers (abstract/overview/full)+- **Semantic Search**: Quick and deep search with intent analysis+- **Feishu Integration**: Import documents from Feishu/Lark (optional)++## Quick Start++```bash+# Install dependencies+uv sync++# Copy and configure+cp ov.conf.example ov.conf+# Edit ov.conf with your API keys++# Run Memex+uv run memex+```++## Configuration++Create `ov.conf` from the example:++```json+{+ "embedding": {+ "dense": {+ "api_base": "https://ark.cn-beijing.volces.com/api/v3",+ "api_key": "your-api-key",+ "backend": "volcengine",+ "dimension": "1024",+ "model": "doubao-embedding-vision-250615"+ }+ },+ "vlm": {+ "api_base": "https://ark.cn-beijing.volces.com/api/v3",+ "api_key": "your-api-key",+ "backend": "volcengine",+ "model": "doubao-seed-1-8-251228"+ }+}+```++## Commands++### Knowledge Management+- `/add <path>` - Add file, directory, or URL+- `/rm <uri>` - Remove resource+- `/import <dir>` - Import entire directory++### Browse+- `/ls [uri]` - List directory contents+- `/tree [uri]` - Show directory tree+- `/read <uri>` - Read full content (L2)+- `/abstract <uri>` - Show summary (L0)+- `/overview <uri>` - Show overview (L1)++### Search+- `/find <query>` - Quick semantic search+- `/search <query>` - Deep search with intent analysis+- `/grep <pattern>` - Content pattern search++### Q&A+- `/ask <question>` - Single-turn question+- `/chat` - Toggle multi-turn chat mode+- `/clear` - Clear chat history+- Or just type your question directly!++### Feishu (Optional)+- `/feishu` - Connect to Feishu+- `/feishu-doc <id>` - Import Feishu document+- `/feishu-search <query>` - Search Feishu documents++Set `FEISHU_APP_ID` and `FEISHU_APP_SECRET` environment variables to enable.++### System+- `/stats` - Show knowledge base statistics+- `/info` - Show configuration+- `/help` - Show help+- `/exit` - Exit Memex++## CLI Options++```bash+uv run memex [OPTIONS]++Options:+ --data-path PATH Data storage path (default: ./memex_data)+ --user USER User name (default: default)+ --llm-backend NAME LLM backend: openai or volcengine (default: openai)+ --llm-model MODEL LLM model name (default: gpt-4o-mini)+```++## Data Storage++Data is stored in `./memex_data/` by default:+- `viking://resources/` - Your knowledge base+- `viking://user/memories/` - User preferences and memories+- `viking://agent/skills/` - Agent skills and memories++## Architecture++Memex uses a modular RAG (Retrieval-Augmented Generation) architecture:++```+┌─────────────────────────────────────────────────────────────┐+│ Memex CLI │+├─────────────────────────────────────────────────────────────┤+│ MemexRecipe │+│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │+│ │ Search │ │ Context │ │ LLM Generation │ │+│ │ │→ │ Builder │→ │ + Chat History │ │+│ │ │ │ │ │ │ │+│ └─────────────┘ └─────────────┘ └─────────────────────┘ │+├─────────────────────────────────────────────────────────────┤+│ MemexClient │+│ ┌─────────────────────────────────────────────────────┐ │+│ │ OpenViking Session API │ │+│ │ • Context-aware search with session history │ │+│ │ • Automatic memory extraction on commit │ │+│ └─────────────────────────────────────────────────────┘ │+├─────────────────────────────────────────────────────────────┤+│ OpenViking Core │+│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │+│ │ Storage │ │ Retrieve │ │ Parse │ │ Models │ │+│ │ (Vector) │ │ (Hybrid) │ │ (Files) │ │(VLM/Emb) │ │+│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │+└─────────────────────────────────────────────────────────────┘+```++### Key Components++| Component | File | Description |+|-----------|------|-------------|+| **MemexRecipe** | `rag/recipe.py` | RAG orchestration: search → context → LLM |+| **MemexClient** | `client.py` | OpenViking client wrapper with session support |+| **MemexConfig** | `config.py` | Configuration management |+| **Commands** | `commands/*.py` | CLI command implementations |++### RAG Flow++1. **Session-Aware Search**: Uses OpenViking Session API for context-aware search with intent analysis+2. **Context Building**: Formats search results with source citations+3. **LLM Generation**: Generates response with chat history support+4. **Memory Extraction**: Session commit extracts and stores user/agent memories++## Configuration Options++### RAG Parameters++| Parameter | Default | Description |+|-----------|---------|-------------|+| `search_top_k` | 5 | Number of search results to retrieve |+| `search_score_threshold` | 0.3 | Minimum score for search results |+| `llm_temperature` | 0.7 | LLM response temperature |+| `llm_max_tokens` | 2000 | Maximum tokens in LLM response |++### Environment Variables++| Variable | Description |+|----------|-------------|+| `OPENVIKING_CONFIG_FILE` | Path to OpenViking config file |+| `FEISHU_APP_ID` | Feishu app ID (optional) |+| `FEISHU_APP_SECRET` | Feishu app secret (optional) |++## Development++### Project Structure++```+examples/memex/+├── __init__.py+├── __main__.py # Entry point+├── app.py # Main application+├── client.py # MemexClient wrapper+├── config.py # Configuration+├── rag/+│ ├── __init__.py+│ └── recipe.py # RAG recipe implementation+├── commands/+│ ├── __init__.py+│ ├── base.py # Base command class+│ ├── browse.py # Browse commands (/ls, /tree, /read)+│ ├── feishu.py # Feishu integration+│ ├── knowledge.py # Knowledge management (/add, /rm)+│ ├── query.py # Q&A commands (/ask, /chat)+│ ├── search.py # Search commands (/find, /search)+│ └── system.py # System commands (/stats, /info)+├── ov.conf.example # Example configuration+└── README.md+```++### Running Tests++```bash+# From project root+uv run pytest examples/memex/tests/ -v+```++## License++This project is part of OpenViking and is licensed under the Apache License 2.0.diff --git a/examples/memex/__init__.py b/examples/memex/__init__.pynew file mode 100644index 000000000..a3ee9cd21--- /dev/null+++ b/examples/memex/__init__.py@@ -0,0 +1,14 @@+"""+Memex - Personal Knowledge Assistant++A CLI-based personal knowledge assistant built on OpenViking.+Features:+- Knowledge base management (add files, directories, URLs)+- Intelligent Q&A with RAG+- Memory system with automatic extraction+- Knowledge browsing (L0/L1/L2 context layers)+- Semantic search+- Knowledge base statistics+"""++__version__ = "0.1.0"diff --git a/examples/memex/__main__.py b/examples/memex/__main__.pynew file mode 100644index 000000000..fcaacb1d1--- /dev/null+++ b/examples/memex/__main__.py@@ -0,0 +1,15 @@+#!/usr/bin/env python3+"""+Memex - Personal Knowledge Assistant++Run with:+ python -m memex [options]++Or:+ python examples/memex [options]+"""++from .cli import main++if __name__ == "__main__":+ main()diff --git a/examples/memex/cli.py b/examples/memex/cli.pynew file mode 100644index 000000000..49d19dc0f--- /dev/null+++ b/examples/memex/cli.py@@ -0,0 +1,443 @@+#!/usr/bin/env python3+"""+Memex CLI - Personal Knowledge Assistant++Usage:+ python -m memex.cli [--data-path PATH] [--user USER]++Commands:+ /help Show help+ /add <path> Add file/directory/URL to knowledge base+ /rm <uri> Remove resource+ /import <dir> Import directory+ /ls [uri] List directory contents+ /tree [uri] Show directory tree+ /read <uri> Read full content (L2)+ /abstract <uri> Show summary (L0)+ /overview <uri> Show overview (L1)+ /find <query> Quick semantic search+ /search <query> Deep search with intent analysis+ /grep <pattern> Content search+ /glob <pattern> Pattern matching+ /ask <question> Ask a question (single turn)+ /chat Toggle chat mode (multi-turn)+ /clear Clear chat history+ /stats Show knowledge base statistics+ /info Show configuration+ /exit Exit Memex+"""++# Suppress Pydantic V1 compatibility warning from volcengine SDK+import warnings++warnings.filterwarnings("ignore", message="Core Pydantic V1 functionality")++import argparse+import sys+from typing import Optional++from prompt_toolkit import PromptSession+from prompt_toolkit.history import FileHistory+from prompt_toolkit.auto_suggest import AutoSuggestFromHistory+from rich.console import Console+from rich.panel import Panel+from rich.markdown import Markdown++from config import MemexConfig+from client import MemexClient+from commands import (+ BrowseCommands,+ KnowledgeCommands,+ SearchCommands,+ QueryCommands,+ StatsCommands,+)+from feishu import FeishuCommands+++BANNER = """+╔══════════════════════════════════════════════════════════════╗+║ ║+║ ███╗ ███╗███████╗███╗ ███╗███████╗██╗ ██╗ ║+║ ████╗ ████║██╔════╝████╗ ████║██╔════╝╚██╗██╔╝ ║+║ ██╔████╔██║█████╗ ██╔████╔██║█████╗ ╚███╔╝ ║+║ ██║╚██╔╝██║██╔══╝ ██║╚██╔╝██║██╔══╝ ██╔██╗ ║+║ ██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║███████╗██╔╝ ██╗ ║+║ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝ ║+║ ║+║ Personal Knowledge Assistant powered by OpenViking ║+║ Type /help for commands, or just ask a question ║+║ ║+╚══════════════════════════════════════════════════════════════╝+"""++HELP_TEXT = """+## Knowledge Management+- `/add <path>` Add file, directory, or URL+- `/rm <uri>` Remove resource (use -r for recursive)+- `/import <dir>` Import entire directory++## Browse+- `/ls [uri]` List directory contents+- `/tree [uri]` Show directory tree+- `/read <uri>` Read full content (L2)+- `/abstract <uri>` Show summary (L0)+- `/overview <uri>` Show overview (L1)+- `/stat <uri>` Show resource metadata++## Search+- `/find <query>` Quick semantic search+- `/search <query>` Deep search with intent analysis+- `/grep <pattern>` Content pattern search+- `/glob <pattern>` File pattern matching++## Q&A+- `/ask <question>` Ask a question (single turn)+- `/chat` Toggle chat mode (multi-turn)+- `/clear` Clear chat history+- Or just type your question directly!++## Session (Memory)+- `/session` Show current session info+- `/commit` End session and extract memories+- `/memories` Show extracted memories++## Feishu Integration+- `/feishu` Connect to Feishu+- `/feishu-doc <id>` Import Feishu document+- `/feishu-search <query>` Search Feishu documents+- `/feishu-tools` List available Feishu tools++## System+- `/stats` Show knowledge base statistics+- `/info` Show configuration+- `/help` Show this help+- `/exit` Exit Memex+"""+++class MemexCLI:+ """Memex CLI application."""++ def __init__(self, config: Optional[MemexConfig] = None):+ """Initialize Memex CLI.++ Args:+ config: Memex configuration.+ """+ self.config = config or MemexConfig.from_env()+ self.console = Console()+ self.client: Optional[MemexClient] = None++ # Command handlers (initialized after client)+ self.browse: Optional[BrowseCommands] = None+ self.knowledge: Optional[KnowledgeCommands] = None+ self.search_cmd: Optional[SearchCommands] = None+ self.query: Optional[QueryCommands] = None+ self.stats_cmd: Optional[StatsCommands] = None+ self.feishu: Optional[FeishuCommands] = None++ def initialize(self) -> None:+ """Initialize the client and command handlers."""+ self.console.print("[dim]Initializing Memex...[/dim]")++ self.client = MemexClient(self.config)+ self.client.initialize()++ # Initialize command handlers+ self.browse = BrowseCommands(self.client, self.console)+ self.knowledge = KnowledgeCommands(self.client, self.console)+ self.search_cmd = SearchCommands(self.client, self.console)+ self.query = QueryCommands(self.client, self.console)+ self.stats_cmd = StatsCommands(self.client, self.console)++ # Initialize Feishu commands (optional - may fail if credentials not set)+ try:+ self.feishu = FeishuCommands(self.client, self.console)+ except Exception:+ self.feishu = None+ self.console.print(+ "[dim]Feishu integration not available (set FEISHU_APP_ID and FEISHU_APP_SECRET)[/dim]"+ )++ self.console.print("[green]Memex initialized![/green]")++ def show_banner(self) -> None:+ """Show welcome banner."""+ self.console.print(BANNER, style="cyan")++ def show_help(self) -> None:+ """Show help text."""+ self.console.print(Panel(Markdown(HELP_TEXT), title="Memex Help", border_style="blue"))++ def parse_command(self, user_input: str) -> tuple[str, list[str]]:+ """Parse user input into command and arguments.++ Args:+ user_input: Raw user input.++ Returns:+ Tuple of (command, arguments).+ """+ parts = user_input.strip().split(maxsplit=1)+ if not parts:+ return "", []++ command = parts[0].lower()+ args = parts[1].split() if len(parts) > 1 else []++ # For commands that take a single string argument (like queries)+ if command in ["/ask", "/find", "/search", "/grep"]:+ args = [parts[1]] if len(parts) > 1 else []++ return command, args++ def handle_command(self, user_input: str) -> bool:+ """Handle a command or query.++ Args:+ user_input: User input.++ Returns:+ False if should exit, True otherwise.+ """+ if not user_input.strip():+ return True++ # Check if it's a command+ if user_input.startswith("/"):+ command, args = self.parse_command(user_input)+ return self._dispatch_command(command, args, user_input)+ else:+ # Treat as a question+ self.query.process_input(user_input)+ return True++ def _dispatch_command(self, command: str, args: list[str], raw_input: str) -> bool:+ """Dispatch command to appropriate handler.++ Args:+ command: Command name.+ args: Command arguments.+ raw_input: Original raw input.++ Returns:+ False if should exit, True otherwise.+ """+ # System commands+ if command in ["/exit", "/quit", "/q"]:+ return False+ elif command in ["/help", "/h", "/?"]:+ self.show_help()++ # Knowledge management+ elif command == "/add":+ path = args[0] if args else ""+ target = args[1] if len(args) > 1 else None+ self.knowledge.add(path, target)+ elif command == "/rm":+ uri = args[0] if args else ""+ recursive = "-r" in args or "--recursive" in args+ self.knowledge.rm(uri, recursive)+ elif command == "/import":+ directory = args[0] if args else ""+ target = args[1] if len(args) > 1 else None+ self.knowledge.import_dir(directory, target)+ elif command == "/url":+ url = args[0] if args else ""+ self.knowledge.add_url(url)++ # Browse commands+ elif command == "/ls":+ uri = args[0] if args else None+ self.browse.ls(uri)+ elif command == "/tree":+ uri = args[0] if args else None+ self.browse.tree(uri)+ elif command == "/read":+ uri = args[0] if args else ""+ self.browse.read(uri)+ elif command == "/abstract":+ uri = args[0] if args else ""+ self.browse.abstract(uri)+ elif command == "/overview":+ uri = args[0] if args else ""+ self.browse.overview(uri)+ elif command == "/stat":+ uri = args[0] if args else ""+ self.browse.stat(uri)++ # Search commands+ elif command == "/find":+ # Get the full query after /find+ query = raw_input[len("/find") :].strip()+ self.search_cmd.find(query)+ elif command == "/search":+ query = raw_input[len("/search") :].strip()+ self.search_cmd.search(query)+ elif command == "/grep":+ pattern = args[0] if args else ""+ uri = args[1] if len(args) > 1 else None+ self.search_cmd.grep(uri or self.client.config.default_resource_uri, pattern)+ elif command == "/glob":+ pattern = args[0] if args else ""+ uri = args[1] if len(args) > 1 else None+ self.search_cmd.glob(pattern, uri)++ # Query commands+ elif command == "/ask":+ query = raw_input[len("/ask") :].strip()+ self.query.ask(query)+ elif command == "/chat":+ query = raw_input[len("/chat") :].strip()+ self.query.chat(query)+ elif command == "/clear":+ self.query.clear_history()++ # Session commands+ elif command == "/session":+ self.query.show_session_info()+ elif command == "/commit":+ self.query.commit_session()+ elif command == "/memories":+ self.query.show_memories()++ # Stats commands+ elif command == "/stats":+ self.stats_cmd.stats()+ elif command == "/info":+ self.stats_cmd.info()++ # Feishu commands+ elif command == "/feishu":+ if self.feishu:+ self.feishu.connect()+ else:+ self.console.print(+ "[red]Feishu not available. Set FEISHU_APP_ID and FEISHU_APP_SECRET.[/red]"+ )+ elif command == "/feishu-doc":+ if self.feishu:+ doc_id = args[0] if args else ""+ target = args[1] if len(args) > 1 else None+ self.feishu.import_document(doc_id, target)+ else:+ self.console.print("[red]Feishu not available.[/red]")+ elif command == "/feishu-search":+ if self.feishu:+ query = raw_input[len("/feishu-search") :].strip()+ self.feishu.search_and_import(query)+ else:+ self.console.print("[red]Feishu not available.[/red]")+ elif command == "/feishu-tools":+ if self.feishu:+ self.feishu.list_tools()+ else:+ self.console.print("[red]Feishu not available.[/red]")++ else:+ self.console.print(f"[red]Unknown command: {command}[/red]")+ self.console.print("[dim]Type /help for available commands[/dim]")++ return True++ def run(self) -> None:+ """Run the CLI main loop."""+ self.show_banner()++ try:+ self.initialize()+ except Exception as e:+ self.console.print(f"[red]Failed to initialize: {e}[/red]")+ return++ # Create prompt session with history+ session = PromptSession(+ history=FileHistory(".memex_history"),+ auto_suggest=AutoSuggestFromHistory(),+ )++ # Main loop+ while True:+ try:+ # Show chat mode indicator+ if self.query.chat_mode:+ prompt = "[chat] memex> "+ else:+ prompt = "memex> "++ user_input = session.prompt(prompt)++ if not self.handle_command(user_input):+ break++ except KeyboardInterrupt:+ self.console.print("\n[dim]Use /exit to quit[/dim]")+ continue+ except EOFError:+ break+ except Exception as e:+ self.console.print(f"[red]Error: {e}[/red]")++ # Cleanup+ self.console.print("\n[cyan]Goodbye! 👋[/cyan]")+ self._cleanup()++ def _cleanup(self) -> None:+ """Clean up resources on exit."""+ # Close Feishu connection if active+ if self.feishu:+ try:+ self.feishu.disconnect()+ except Exception:+ pass++ # Close OpenViking client+ if self.client:+ try:+ self.client.close()+ except Exception:+ pass++ # Kill any remaining AGFS processes for this data path+ import subprocess++ try:+ subprocess.run(+ ["pkill", "-f", "agfs-server"],+ capture_output=True,+ timeout=5,+ )+ except Exception:+ pass+++def main():+ """Main entry point."""+ parser = argparse.ArgumentParser(description="Memex - Personal Knowledge Assistant")+ parser.add_argument(+ "--data-path",+ default="./memex_data",+ help="Path to store Memex data (default: ./memex_data)",+ )+ parser.add_argument(+ "--config-path",+ default="./ov.conf",+ help="Path to OpenViking config file (default: ./ov.conf)",+ )+ parser.add_argument("--user", default="default", help="User name (default: default)")++ args = parser.parse_args()++ config = MemexConfig(+ data_path=args.data_path,+ config_path=args.config_path,+ user=args.user,+ )++ cli = MemexCLI(config)+ cli.run()+++if __name__ == "__main__":+ main()diff --git a/examples/memex/client.py b/examples/memex/client.pynew file mode 100644index 000000000..c51ebcc09--- /dev/null+++ b/examples/memex/client.py@@ -0,0 +1,318 @@+"""+Memex Client - OpenViking client wrapper for Memex.+"""++from typing import Any, Optional++import openviking as ov++from config import MemexConfig+++class MemexClient:+ """OpenViking client wrapper for Memex."""++ def __init__(self, config: Optional[MemexConfig] = None):+ """Initialize Memex client.++ Args:+ config: Memex configuration. If None, uses default config from env.+ """+ self.config = config or MemexConfig.from_env()+ self._client: Optional[ov.SyncOpenViking] = None+ self._session = None++ @property+ def client(self) -> ov.SyncOpenViking:+ """Get the OpenViking client instance."""+ if self._client is None:+ raise RuntimeError("Client not initialized. Call initialize() first.")+ return self._client++ def initialize(self) -> None:+ """Initialize the OpenViking client."""+ ov_config = self.config.get_openviking_config()+ self._client = ov.SyncOpenViking(+ path=self.config.data_path,+ config=ov_config,+ user=self.config.user,+ )+ self._client.initialize()++ def close(self) -> None:+ """Close the client."""+ if self._client is not None:+ self._client.close()+ self._client = None++ # ==================== Resource Management ====================++ def add_resource(+ self,+ path: str,+ target: Optional[str] = None,+ reason: Optional[str] = None,+ instruction: Optional[str] = None,+ ) -> dict[str, Any]:+ """Add a resource to the knowledge base.++ Args:+ path: File path, directory path, or URL.+ target: Target URI in viking://. Defaults to viking://resources/.+ reason: Reason for adding this resource.+ instruction: Special instructions for processing.++ Returns:+ Dict with root_uri and other metadata.+ """+ target = target or self.config.default_resource_uri+ return self.client.add_resource(+ path=path,+ target=target,+ reason=reason,+ instruction=instruction,+ )++ def remove(self, uri: str, recursive: bool = False) -> None:+ """Remove a resource from the knowledge base.++ Args:+ uri: URI of the resource to remove.+ recursive: Whether to remove recursively.+ """+ self.client.rm(uri=uri, recursive=recursive)++ def wait_processed(self, timeout: Optional[float] = None) -> None:+ """Wait for all pending resources to be processed.++ Args:+ timeout: Maximum time to wait in seconds.+ """+ self.client.wait_processed(timeout=timeout)++ # ==================== File System Operations ====================++ def ls(self, uri: Optional[str] = None) -> list[dict[str, Any]]:+ """List contents of a directory.++ Args:+ uri: URI to list. Defaults to viking://resources/.++ Returns:+ List of items in the directory.+ """+ uri = uri or self.config.default_resource_uri+ return self.client.ls(uri=uri)++ def tree(self, uri: Optional[str] = None) -> str:+ """Get directory tree as string.++ Args:+ uri: URI to get tree for. Defaults to viking://resources/.++ Returns:+ Tree structure as string.+ """+ uri = uri or self.config.default_resource_uri+ return self.client.tree(uri=uri)++ def read(self, uri: str) -> str:+ """Read full content of a resource (L2).++ Args:+ uri: URI of the resource.++ Returns:+ Full content of the resource.+ """+ return self.client.read(uri=uri)++ def abstract(self, uri: str) -> str:+ """Get abstract/summary of a resource (L0).++ Args:+ uri: URI of the resource.++ Returns:+ Abstract/summary of the resource.+ """+ return self.client.abstract(uri=uri)++ def overview(self, uri: str) -> str:+ """Get overview of a resource (L1).++ Args:+ uri: URI of the resource.++ Returns:+ Overview of the resource.+ """+ return self.client.overview(uri=uri)++ def glob(self, pattern: str, uri: Optional[str] = None) -> list[str]:+ """Find resources matching a pattern.++ Args:+ pattern: Glob pattern to match.+ uri: Base URI to search in.++ Returns:+ List of matching URIs.+ """+ uri = uri or self.config.default_resource_uri+ return self.client.glob(pattern=pattern, uri=uri)++ def grep(self, uri: str, pattern: str) -> list[dict[str, Any]]:+ """Search content within resources.++ Args:+ uri: URI to search in.+ pattern: Pattern to search for.++ Returns:+ List of matches.+ """+ return self.client.grep(uri=uri, pattern=pattern)++ def stat(self, uri: str) -> dict[str, Any]:+ """Get metadata about a resource.++ Args:+ uri: URI of the resource.++ Returns:+ Resource metadata.+ """+ return self.client.stat(uri=uri)++ # ==================== Search ====================++ def find(+ self,+ query: str,+ target_uri: Optional[str] = None,+ top_k: Optional[int] = None,+ score_threshold: Optional[float] = None,+ ) -> Any:+ """Quick semantic search.++ Args:+ query: Search query.+ target_uri: URI to search in.+ top_k: Number of results to return.+ score_threshold: Minimum score threshold.++ Returns:+ Search results.+ """+ target_uri = target_uri or self.config.default_resource_uri+ limit = top_k or self.config.search_top_k+ score_threshold = score_threshold or self.config.search_score_threshold+ return self.client.find(+ query=query,+ target_uri=target_uri,+ limit=limit,+ score_threshold=score_threshold,+ )++ def search(+ self,+ query: str,+ target_uri: Optional[str] = None,+ top_k: Optional[int] = None,+ score_threshold: Optional[float] = None,+ session: Optional[Any] = None,+ ) -> Any:+ """Deep semantic search with intent analysis.++ Args:+ query: Search query.+ target_uri: URI to search in.+ top_k: Number of results to return.+ score_threshold: Minimum score threshold.+ session: OpenViking Session for context-aware search.++ Returns:+ Search results.+ """+ target_uri = target_uri or self.config.default_resource_uri+ limit = top_k or self.config.search_top_k+ score_threshold = score_threshold or self.config.search_score_threshold+ return self.client.search(+ query=query,+ target_uri=target_uri,+ limit=limit,+ score_threshold=score_threshold,+ session=session,+ )++ # ==================== Session Management ====================++ def get_session(self, session_id: Optional[str] = None):+ """Get or create a session.++ Args:+ session_id: Session ID. If None, uses config session_id or generates one.++ Returns:+ Session object.+ """+ session_id = session_id or self.config.session_id+ if session_id:+ self._session = self.client.session(session_id=session_id)+ else:+ self._session = self.client.session()+ return self._session++ @property+ def session(self):+ """Get current session."""+ return self._session++ # ==================== Statistics ====================++ def get_stats(self) -> dict[str, Any]:+ """Get knowledge base statistics.++ Returns:+ Statistics about the knowledge base.+ """+ stats = {+ "resources": {"count": 0, "types": {}},+ "user": {"memories": 0},+ "agent": {"skills": 0, "memories": 0},+ }++ # Count resources+ try:+ resources = self.ls(self.config.default_resource_uri)+ stats["resources"]["count"] = len(resources)+ for item in resources:+ item_type = item.get("type", "unknown")+ stats["resources"]["types"][item_type] = (+ stats["resources"]["types"].get(item_type, 0) + 1+ )+ except Exception:+ pass++ # Count user memories+ try:+ user_memories = self.ls(f"{self.config.default_user_uri}memories/")+ stats["user"]["memories"] = len(user_memories)+ except Exception:+ pass++ # Count agent skills and memories+ try:+ agent_skills = self.ls(f"{self.config.default_agent_uri}skills/")+ stats["agent"]["skills"] = len(agent_skills)+ except Exception:+ pass++ try:+ agent_memories = self.ls(f"{self.config.default_agent_uri}memories/")+ stats["agent"]["memories"] = len(agent_memories)+ except Exception:+ pass++ return statsdiff --git a/examples/memex/commands/__init__.py b/examples/memex/commands/__init__.pynew file mode 100644index 000000000..d6adf1f39--- /dev/null+++ b/examples/memex/commands/__init__.py@@ -0,0 +1,17 @@+"""+Memex Commands module.+"""++from .browse import BrowseCommands+from .knowledge import KnowledgeCommands+from .search import SearchCommands+from .query import QueryCommands+from .stats import StatsCommands++__all__ = [+ "BrowseCommands",+ "KnowledgeCommands",+ "SearchCommands",+ "QueryCommands",+ "StatsCommands",+]diff --git a/examples/memex/commands/browse.py b/examples/memex/commands/browse.pynew file mode 100644index 000000000..4551f7c77--- /dev/null+++ b/examples/memex/commands/browse.py@@ -0,0 +1,224 @@+"""+Browse commands for Memex - ls, tree, read, abstract, overview.+"""++from typing import Optional++from rich.console import Console+from rich.panel import Panel+from rich.tree import Tree+from rich.table import Table+from rich.markdown import Markdown++from client import MemexClient+++class BrowseCommands:+ """Browse commands for navigating the knowledge base."""++ def __init__(self, client: MemexClient, console: Console):+ """Initialize browse commands.++ Args:+ client: Memex client instance.+ console: Rich console for output.+ """+ self.client = client+ self.console = console++ def ls(self, uri: Optional[str] = None) -> None:+ """List contents of a directory.++ Args:+ uri: URI to list. Defaults to viking://resources/.+ """+ uri = uri or self.client.config.default_resource_uri++ try:+ items = self.client.ls(uri)++ if not items:+ self.console.print(f"[dim]Empty directory: {uri}[/dim]")+ return++ table = Table(title=f"Contents of {uri}", show_header=True)+ table.add_column("Name", style="cyan")+ table.add_column("Type", style="green")+ table.add_column("Size", style="yellow", justify="right")++ for item in items:+ name = item.get("name", "unknown")+ item_type = item.get("type", "unknown")+ size = item.get("size", "-")++ # Format type with icon+ if item_type == "directory":+ type_display = "📁 dir"+ elif item_type == "file":+ type_display = "📄 file"+ else:+ type_display = f"📦 {item_type}"++ table.add_row(name, type_display, str(size))++ self.console.print(table)++ except Exception as e:+ self.console.print(f"[red]Error listing {uri}: {e}[/red]")++ def tree(self, uri: Optional[str] = None) -> None:+ """Display directory tree.++ Args:+ uri: URI to show tree for. Defaults to viking://resources/.+ """+ uri = uri or self.client.config.default_resource_uri++ try:+ tree_result = self.client.tree(uri)++ # Handle different return types+ if isinstance(tree_result, str):+ tree_str = tree_result+ elif isinstance(tree_result, list):+ # Build tree from list of items+ lines = []+ for item in tree_result:+ if isinstance(item, dict):+ name = item.get("name", "unknown")+ is_dir = item.get("isDir", False)+ prefix = "📁 " if is_dir else "📄 "+ lines.append(f"{prefix}{name}")+ else:+ lines.append(str(item))+ tree_str = "\n".join(lines)+ else:+ tree_str = str(tree_result) if tree_result else ""++ if tree_str:+ self.console.print(Panel(tree_str, title=f"Tree: {uri}", border_style="blue"))+ else:+ self.console.print(f"[dim]Empty or not found: {uri}[/dim]")++ except Exception as e:+ self.console.print(f"[red]Error getting tree for {uri}: {e}[/red]")++ def read(self, uri: str) -> None:+ """Read full content of a resource (L2).++ Args:+ uri: URI of the resource to read.+ """+ if not uri:+ self.console.print("[red]Usage: /read <uri>[/red]")+ return++ try:+ content = self.client.read(uri)++ if content:+ # Try to render as markdown if it looks like markdown+ if uri.endswith(".md") or "```" in content or content.startswith("#"):+ self.console.print(+ Panel(Markdown(content), title=f"📄 {uri}", border_style="green")+ )+ else:+ self.console.print(Panel(content, title=f"📄 {uri}", border_style="green"))+ else:+ self.console.print(f"[dim]Empty content: {uri}[/dim]")++ except Exception as e:+ self.console.print(f"[red]Error reading {uri}: {e}[/red]")++ def abstract(self, uri: str) -> None:+ """Show abstract/summary of a resource (L0).++ Args:+ uri: URI of the resource.+ """+ if not uri:+ self.console.print("[red]Usage: /abstract <uri>[/red]")+ return++ # Remove trailing slash if present+ uri = uri.rstrip("/")++ try:+ content = self.client.abstract(uri)++ if content:+ self.console.print(+ Panel(+ content,+ title=f"📝 Abstract: {uri}",+ subtitle="[dim]L0 - Quick Summary[/dim]",+ border_style="cyan",+ )+ )+ else:+ self.console.print(f"[dim]No abstract available: {uri}[/dim]")++ except Exception as e:+ self.console.print(f"[red]Error getting abstract for {uri}: {e}[/red]")++ def overview(self, uri: str) -> None:+ """Show overview of a resource (L1).++ Args:+ uri: URI of the resource.+ """+ if not uri:+ self.console.print("[red]Usage: /overview <uri>[/red]")+ return++ # Remove trailing slash if present+ uri = uri.rstrip("/")++ try:+ content = self.client.overview(uri)++ if content:+ # Try to render as markdown+ self.console.print(+ Panel(+ Markdown(content)+ if "```" in content or content.startswith("#")+ else content,+ title=f"📋 Overview: {uri}",+ subtitle="[dim]L1 - Detailed Summary[/dim]",+ border_style="yellow",+ )+ )+ else:+ self.console.print(f"[dim]No overview available: {uri}[/dim]")++ except Exception as e:+ self.console.print(f"[red]Error getting overview for {uri}: {e}[/red]")++ def stat(self, uri: str) -> None:+ """Show metadata about a resource.++ Args:+ uri: URI of the resource.+ """+ if not uri:+ self.console.print("[red]Usage: /stat <uri>[/red]")+ return++ try:+ metadata = self.client.stat(uri)++ if metadata:+ table = Table(title=f"Metadata: {uri}", show_header=True)+ table.add_column("Property", style="cyan")+ table.add_column("Value", style="white")++ for key, value in metadata.items():+ table.add_row(str(key), str(value))++ self.console.print(table)+ else:+ self.console.print(f"[dim]No metadata available: {uri}[/dim]")++ except Exception as e:+ self.console.print(f"[red]Error getting metadata for {uri}: {e}[/red]")diff --git a/examples/memex/commands/knowledge.py b/examples/memex/commands/knowledge.pynew file mode 100644index 000000000..9e49ef7e5--- /dev/null+++ b/examples/memex/commands/knowledge.py@@ -0,0 +1,281 @@+"""+Knowledge management commands for Memex - add, rm, import.+"""++import os+from typing import Optional++from rich.console import Console+from rich.progress import Progress, SpinnerColumn, TextColumn+from rich.panel import Panel++from client import MemexClient+++class KnowledgeCommands:+ """Knowledge management commands for adding and removing resources."""++ def __init__(self, client: MemexClient, console: Console):+ """Initialize knowledge commands.++ Args:+ client: Memex client instance.+ console: Rich console for output.+ """+ self.client = client+ self.console = console++ def add(+ self,+ path: str,+ target: Optional[str] = None,+ reason: Optional[str] = None,+ instruction: Optional[str] = None,+ wait: bool = True,+ ) -> None:+ if not path:+ self.console.print("[red]Usage: /add <path> [target] [reason][/red]")+ return++ if path.startswith("~"):+ path = os.path.expanduser(path)++ if not path.startswith(("http://", "https://")) and not os.path.exists(path):+ self.console.print(f"[red]Path not found: {path}[/red]")+ return++ is_dir = os.path.isdir(path)+ if is_dir:+ self._add_directory(path, target, reason, instruction, wait)+ else:+ self._add_file(path, target, reason, instruction, wait)++ def _add_file(+ self,+ path: str,+ target: Optional[str] = None,+ reason: Optional[str] = None,+ instruction: Optional[str] = None,+ wait: bool = True,+ ) -> None:+ try:+ with Progress(+ SpinnerColumn(),+ TextColumn("[progress.description]{task.description}"),+ console=self.console,+ ) as progress:+ task = progress.add_task(f"Adding {path}...", total=None)++ result = self.client.add_resource(+ path=path,+ target=target,+ reason=reason,+ instruction=instruction,+ )++ status = result.get("status", "unknown")+ errors = result.get("errors", [])+ root_uri = result.get("root_uri", "unknown")++ if status == "error" or errors:+ error_msg = errors[0] if errors else "Unknown error"+ self.console.print(f"[red]Error: {error_msg}[/red]")+ return++ progress.update(task, description=f"Added to {root_uri}")++ if wait:+ progress.update(task, description="Processing...")+ self.client.wait_processed(timeout=120)+ progress.update(task, description="Done!")++ self.console.print(+ Panel(+ f"[green]✓[/green] Added: {path}\n[cyan]URI:[/cyan] {root_uri}",+ title="Resource Added",+ border_style="green",+ )+ )++ except Exception as e:+ self.console.print(f"[red]Error adding resource: {e}[/red]")++ def _add_directory(+ self,+ directory: str,+ target: Optional[str] = None,+ reason: Optional[str] = None,+ instruction: Optional[str] = None,+ wait: bool = True,+ ) -> None:+ supported_extensions = {+ ".txt",+ ".md",+ ".markdown",+ ".rst",+ ".py",+ ".js",+ ".ts",+ ".jsx",+ ".tsx",+ ".java",+ ".c",+ ".cpp",+ ".h",+ ".hpp",+ ".go",+ ".rs",+ ".rb",+ ".php",+ ".swift",+ ".kt",+ ".scala",+ ".sh",+ ".bash",+ ".json",+ ".yaml",+ ".yml",+ ".toml",+ ".xml",+ ".html",+ ".css",+ ".scss",+ ".pdf",+ ".doc",+ ".docx",+ }++ files_to_add = []+ for root, dirs, files in os.walk(directory):+ dirs[:] = [d for d in dirs if not d.startswith(".")]+ for file in files:+ if file.startswith("."):+ continue+ ext = os.path.splitext(file)[1].lower()+ if ext in supported_extensions:+ files_to_add.append(os.path.join(root, file))++ if not files_to_add:+ self.console.print(f"[yellow]No supported files found in {directory}[/yellow]")+ return++ self.console.print(f"[dim]Found {len(files_to_add)} files to add...[/dim]")++ success_count = 0+ error_count = 0+ added_uris = []++ with Progress(+ SpinnerColumn(),+ TextColumn("[progress.description]{task.description}"),+ console=self.console,+ ) as progress:+ task = progress.add_task(f"Adding files from {directory}...", total=len(files_to_add))++ for i, file_path in enumerate(files_to_add):+ progress.update(+ task,+ description=f"Adding ({i + 1}/{len(files_to_add)}): {os.path.basename(file_path)}",+ )++ try:+ result = self.client.add_resource(+ path=file_path,+ target=target,+ reason=reason or f"Imported from {directory}",+ instruction=instruction,+ )++ status = result.get("status", "unknown")+ errors = result.get("errors", [])++ if status == "error" or errors:+ error_count += 1+ else:+ success_count += 1+ root_uri = result.get("root_uri", "")+ if root_uri:+ added_uris.append(root_uri)++ except Exception:+ error_count += 1++ progress.advance(task)++ if wait and success_count > 0:+ progress.update(task, description="Processing...")+ self.client.wait_processed(timeout=300)++ progress.update(task, description="Done!")++ self.console.print(+ Panel(+ f"[green]✓[/green] Added {success_count} files from {directory}\n"+ f"[red]✗[/red] Failed: {error_count} files",+ title="Directory Import Complete",+ border_style="green" if error_count == 0 else "yellow",+ )+ )++ def rm(self, uri: str, recursive: bool = False) -> None:+ """Remove a resource from the knowledge base.++ Args:+ uri: URI of the resource to remove.+ recursive: Whether to remove recursively.+ """+ if not uri:+ self.console.print("[red]Usage: /rm <uri> [-r][/red]")+ return++ try:+ self.client.remove(uri=uri, recursive=recursive)+ self.console.print(f"[green]✓[/green] Removed: {uri}")++ except Exception as e:+ self.console.print(f"[red]Error removing {uri}: {e}[/red]")++ def import_dir(+ self,+ directory: str,+ target: Optional[str] = None,+ reason: Optional[str] = None,+ wait: bool = True,+ ) -> None:+ if not directory:+ self.console.print("[red]Usage: /import <directory> [target][/red]")+ return++ if directory.startswith("~"):+ directory = os.path.expanduser(directory)++ if not os.path.isdir(directory):+ self.console.print(f"[red]Not a directory: {directory}[/red]")+ return++ self._add_directory(directory, target, reason, wait=wait)++ def add_url(+ self,+ url: str,+ target: Optional[str] = None,+ reason: Optional[str] = None,+ wait: bool = True,+ ) -> None:+ """Add a URL resource to the knowledge base.++ Args:+ url: URL to add.+ target: Target URI in viking://.+ reason: Reason for adding.+ wait: Whether to wait for processing.+ """+ if not url:+ self.console.print("[red]Usage: /url <url> [target][/red]")+ return++ if not url.startswith(("http://", "https://")):+ self.console.print("[red]Invalid URL. Must start with http:// or https://[/red]")+ return++ self.add(path=url, target=target, reason=reason, wait=wait)diff --git a/examples/memex/commands/query.py b/examples/memex/commands/query.pynew file mode 100644index 000000000..122434dd3--- /dev/null+++ b/examples/memex/commands/query.py@@ -0,0 +1,196 @@+"""+Query commands for Memex - ask, chat with RAG.+"""++from typing import Optional++from rich.console import Console+from rich.panel import Panel+from rich.markdown import Markdown+from rich.progress import Progress, SpinnerColumn, TextColumn++from client import MemexClient+from rag.recipe import MemexRecipe+++class QueryCommands:+ """Query commands for RAG-based Q&A."""++ def __init__(self, client: MemexClient, console: Console):+ self.client = client+ self.console = console+ self._recipe: Optional[MemexRecipe] = None+ self._chat_mode = False++ @property+ def recipe(self) -> MemexRecipe:+ if self._recipe is None:+ self._recipe = MemexRecipe(self.client)+ self._recipe.start_session()+ return self._recipe++ def ask(self, query: str, target_uri: Optional[str] = None) -> None:+ if not query:+ self.console.print("[red]Usage: /ask <question>[/red]")+ return++ try:+ with Progress(+ SpinnerColumn(),+ TextColumn("[progress.description]{task.description}"),+ console=self.console,+ ) as progress:+ task = progress.add_task("Searching knowledge base...", total=None)++ response = self.recipe.query(+ user_query=query,+ target_uri=target_uri,+ use_chat_history=False,+ )++ progress.update(task, description="Done!")++ self.console.print()+ self.console.print(+ Panel(+ Markdown(response),+ title="[bold cyan]Memex[/bold cyan]",+ border_style="cyan",+ )+ )++ except Exception as e:+ self.console.print(f"[red]Error: {e}[/red]")++ def chat(self, query: str, target_uri: Optional[str] = None) -> None:+ if not query:+ self._chat_mode = not self._chat_mode+ if self._chat_mode:+ self.console.print(+ "[green]Chat mode enabled. Type your questions directly.[/green]"+ )+ self.console.print(+ "[dim]Use /clear to clear history, /exit to exit chat mode.[/dim]"+ )+ else:+ self.console.print("[yellow]Chat mode disabled.[/yellow]")+ return++ try:+ with Progress(+ SpinnerColumn(),+ TextColumn("[progress.description]{task.description}"),+ console=self.console,+ ) as progress:+ task = progress.add_task("Thinking...", total=None)++ response = self.recipe.query(+ user_query=query,+ target_uri=target_uri,+ use_chat_history=True,+ )++ progress.update(task, description="Done!")++ self.console.print()+ self.console.print(+ Panel(+ Markdown(response),+ title="[bold cyan]Memex[/bold cyan]",+ border_style="cyan",+ )+ )++ except Exception as e:+ self.console.print(f"[red]Error: {e}[/red]")++ def clear_history(self) -> None:+ self.recipe.clear_history()+ self.console.print("[green]Chat history cleared.[/green]")++ @property+ def chat_mode(self) -> bool:+ return self._chat_mode++ @chat_mode.setter+ def chat_mode(self, value: bool) -> None:+ self._chat_mode = value++ def process_input(self, user_input: str, target_uri: Optional[str] = None) -> None:+ if self._chat_mode:+ self.chat(user_input, target_uri)+ else:+ self.ask(user_input, target_uri)++ def show_session_info(self) -> None:+ session = self.recipe.session+ if not session:+ self.console.print("[yellow]No active session.[/yellow]")+ return++ session_id = self.recipe.session_id+ msg_count = len(session.messages) if hasattr(session, "messages") else 0++ self.console.print(+ Panel(+ f"Session ID: {session_id}\n"+ f"Messages: {msg_count}\n"+ f"Chat history: {len(self.recipe.chat_history)} turns",+ title="[bold cyan]Session Info[/bold cyan]",+ border_style="cyan",+ )+ )++ def commit_session(self) -> None:+ with Progress(+ SpinnerColumn(),+ TextColumn("[progress.description]{task.description}"),+ console=self.console,+ ) as progress:+ task = progress.add_task("Extracting memories...", total=None)++ result = self.recipe.end_session()++ progress.update(task, description="Done!")++ if result.get("status") == "no_session":+ self.console.print("[yellow]No active session to commit.[/yellow]")+ elif result.get("status") == "error":+ self.console.print(f"[red]Error: {result.get('error')}[/red]")+ else:+ memories = result.get("memories_extracted", 0)+ self.console.print(+ Panel(+ f"Session committed!\n"+ f"Memories extracted: {memories}\n"+ f"Status: {result.get('status', 'unknown')}",+ title="[bold green]Session Committed[/bold green]",+ border_style="green",+ )+ )+ self._recipe.start_session()++ def show_memories(self) -> None:+ try:+ user_memories = self.client.ls("viking://user/memories/")+ agent_memories = self.client.ls("viking://agent/memories/")++ output = "## User Memories\n"+ for item in user_memories:+ name = item.get("name", str(item))+ output += f"- {name}\n"++ output += "\n## Agent Memories\n"+ for item in agent_memories:+ name = item.get("name", str(item))+ output += f"- {name}\n"++ self.console.print(+ Panel(+ Markdown(output),+ title="[bold cyan]Extracted Memories[/bold cyan]",+ border_style="cyan",+ )+ )+ except Exception as e:+ self.console.print(f"[red]Error listing memories: {e}[/red]")diff --git a/examples/memex/commands/search.py b/examples/memex/commands/search.pynew file mode 100644index 000000000..686b15e43--- /dev/null+++ b/examples/memex/commands/search.py@@ -0,0 +1,229 @@+"""+Search commands for Memex - find, search, grep.+"""++from typing import Optional++from rich.console import Console+from rich.table import Table+from rich.panel import Panel+from rich.progress import Progress, SpinnerColumn, TextColumn++from client import MemexClient+++class SearchCommands:+ """Search commands for finding content in the knowledge base."""++ def __init__(self, client: MemexClient, console: Console):+ """Initialize search commands.++ Args:+ client: Memex client instance.+ console: Rich console for output.+ """+ self.client = client+ self.console = console++ def find(+ self,+ query: str,+ target_uri: Optional[str] = None,+ top_k: Optional[int] = None,+ ) -> None:+ """Quick semantic search.++ Args:+ query: Search query.+ target_uri: URI to search in.+ top_k: Number of results.+ """+ if not query:+ self.console.print("[red]Usage: /find <query> [uri][/red]")+ return++ try:+ with Progress(+ SpinnerColumn(),+ TextColumn("[progress.description]{task.description}"),+ console=self.console,+ ) as progress:+ task = progress.add_task("Searching...", total=None)++ results = self.client.find(+ query=query,+ target_uri=target_uri,+ top_k=top_k,+ )++ progress.update(task, description="Done!")++ self._display_results(results, query, "Find Results")++ except Exception as e:+ self.console.print(f"[red]Error searching: {e}[/red]")++ def search(+ self,+ query: str,+ target_uri: Optional[str] = None,+ top_k: Optional[int] = None,+ ) -> None:+ """Deep semantic search with intent analysis.++ Args:+ query: Search query.+ target_uri: URI to search in.+ top_k: Number of results.+ """+ if not query:+ self.console.print("[red]Usage: /search <query> [uri][/red]")+ return++ try:+ with Progress(+ SpinnerColumn(),+ TextColumn("[progress.description]{task.description}"),+ console=self.console,+ ) as progress:+ task = progress.add_task("Analyzing intent and searching...", total=None)++ results = self.client.search(+ query=query,+ target_uri=target_uri,+ top_k=top_k,+ )++ progress.update(task, description="Done!")++ self._display_results(results, query, "Search Results (Deep)")++ except Exception as e:+ self.console.print(f"[red]Error searching: {e}[/red]")++ def grep(self, uri: str, pattern: str) -> None:+ """Search content within resources using pattern.++ Args:+ uri: URI to search in.+ pattern: Pattern to search for.+ """+ if not pattern:+ self.console.print("[red]Usage: /grep <pattern> [uri][/red]")+ return++ uri = uri or self.client.config.default_resource_uri++ try:+ with Progress(+ SpinnerColumn(),+ TextColumn("[progress.description]{task.description}"),+ console=self.console,+ ) as progress:+ task = progress.add_task(f"Searching for '{pattern}'...", total=None)++ results = self.client.grep(uri=uri, pattern=pattern)++ progress.update(task, description="Done!")++ if not results:+ self.console.print(f"[dim]No matches found for '{pattern}' in {uri}[/dim]")+ return++ table = Table(title=f"Grep Results: '{pattern}'", show_header=True)+ table.add_column("URI", style="cyan")+ table.add_column("Match", style="white")++ for result in results[:20]: # Limit to 20 results+ result_uri = result.get("uri", "unknown")+ match = result.get("match", result.get("content", ""))+ # Truncate long matches+ if len(match) > 100:+ match = match[:100] + "..."+ table.add_row(result_uri, match)++ self.console.print(table)++ if len(results) > 20:+ self.console.print(f"[dim]... and {len(results) - 20} more matches[/dim]")++ except Exception as e:+ self.console.print(f"[red]Error grepping: {e}[/red]")++ def glob(self, pattern: str, uri: Optional[str] = None) -> None:+ """Find resources matching a glob pattern.++ Args:+ pattern: Glob pattern (e.g., *.md, **/*.py).+ uri: Base URI to search in.+ """+ if not pattern:+ self.console.print("[red]Usage: /glob <pattern> [uri][/red]")+ return++ try:+ results = self.client.glob(pattern=pattern, uri=uri)++ if not results:+ self.console.print(f"[dim]No matches found for '{pattern}'[/dim]")+ return++ self.console.print(+ Panel("\n".join(results[:50]), title=f"Glob: {pattern}", border_style="blue")+ )++ if len(results) > 50:+ self.console.print(f"[dim]... and {len(results) - 50} more matches[/dim]")++ except Exception as e:+ self.console.print(f"[red]Error globbing: {e}[/red]")++ def _display_results(self, results, query: str, title: str) -> None:+ """Display search results.++ Args:+ results: Search results object or list.+ query: Original query.+ title: Title for the results panel.+ """+ # Extract resources from results+ resources = []+ if hasattr(results, "resources"):+ resources = results.resources+ elif isinstance(results, list):+ resources = results++ if not resources:+ self.console.print(f"[dim]No results found for: {query}[/dim]")+ return++ table = Table(title=title, show_header=True)+ table.add_column("#", style="dim", width=3)+ table.add_column("URI", style="cyan")+ table.add_column("Score", style="green", justify="right")+ table.add_column("Preview", style="white", max_width=50)++ for i, r in enumerate(resources[:10], 1):+ if hasattr(r, "uri"):+ uri = r.uri+ score = f"{r.score:.3f}" if hasattr(r, "score") else "-"+ content = r.content if hasattr(r, "content") else ""+ elif isinstance(r, dict):+ uri = r.get("uri", "unknown")+ score = f"{r.get('score', 0):.3f}"+ content = r.get("content", "")+ else:+ uri = str(r)+ score = "-"+ content = ""++ # Truncate content for preview+ preview = content[:100] + "..." if len(content) > 100 else content+ preview = preview.replace("\n", " ")++ table.add_row(str(i), uri, score, preview)++ self.console.print(table)++ if len(resources) > 10:+ self.console.print(f"[dim]Showing top 10 of {len(resources)} results[/dim]")diff --git a/examples/memex/commands/stats.py b/examples/memex/commands/stats.pynew file mode 100644index 000000000..9e4843db1--- /dev/null+++ b/examples/memex/commands/stats.py@@ -0,0 +1,74 @@+"""+Stats commands for Memex - knowledge base statistics.+"""++from rich.console import Console+from rich.table import Table+from rich.panel import Panel++from client import MemexClient+++class StatsCommands:+ """Statistics commands for the knowledge base."""++ def __init__(self, client: MemexClient, console: Console):+ """Initialize stats commands.++ Args:+ client: Memex client instance.+ console: Rich console for output.+ """+ self.client = client+ self.console = console++ def stats(self) -> None:+ """Display knowledge base statistics."""+ try:+ stats = self.client.get_stats()++ # Create main stats panel+ table = Table(title="Knowledge Base Statistics", show_header=True)+ table.add_column("Category", style="cyan")+ table.add_column("Metric", style="white")+ table.add_column("Value", style="green", justify="right")++ # Resources+ table.add_row("📚 Resources", "Total", str(stats["resources"]["count"]))+ for type_name, count in stats["resources"]["types"].items():+ table.add_row("", f" {type_name}", str(count))++ # User+ table.add_row("👤 User", "Memories", str(stats["user"]["memories"]))++ # Agent+ table.add_row("🤖 Agent", "Skills", str(stats["agent"]["skills"]))+ table.add_row("", "Memories", str(stats["agent"]["memories"]))++ self.console.print(table)++ except Exception as e:+ self.console.print(f"[red]Error getting stats: {e}[/red]")++ def info(self) -> None:+ """Display system information."""+ config = self.client.config++ # Get VLM config for display+ try:+ vlm_config = config.get_vlm_config()+ llm_backend = vlm_config.get("backend", "unknown")+ llm_model = vlm_config.get("model", "unknown")+ except Exception:+ llm_backend = "not configured"+ llm_model = "not configured"++ info_text = f"""[cyan]Data Path:[/cyan] {config.data_path}+[cyan]Config Path:[/cyan] {config.config_path}+[cyan]User:[/cyan] {config.user}+[cyan]LLM Backend:[/cyan] {llm_backend}+[cyan]LLM Model:[/cyan] {llm_model}+[cyan]Search Top-K:[/cyan] {config.search_top_k}+[cyan]Score Threshold:[/cyan] {config.search_score_threshold}"""++ self.console.print(Panel(info_text, title="Memex Configuration", border_style="blue"))diff --git a/examples/memex/config.py b/examples/memex/config.pynew file mode 100644index 000000000..b82b419bc--- /dev/null+++ b/examples/memex/config.py@@ -0,0 +1,81 @@+"""+Memex Configuration Management+"""++import json+import os+from dataclasses import dataclass+from pathlib import Path+from typing import Optional++from openviking.utils.config import OpenVikingConfig+++@dataclass+class MemexConfig:+ """Memex configuration."""++ # OpenViking settings+ data_path: str = "./memex_data"+ config_path: str = "./ov.conf"+ user: str = "default"++ # LLM settings (for RAG, read from ov.conf)+ llm_temperature: float = 0.7+ llm_max_tokens: int = 2048++ # Search settings+ search_top_k: int = 5+ search_score_threshold: float = 0.1++ # Session settings+ session_id: Optional[str] = None++ # Default URIs+ default_resource_uri: str = "viking://resources/"+ default_user_uri: str = "viking://user/"+ default_agent_uri: str = "viking://agent/"++ # Cached OpenViking config+ _ov_config: Optional[OpenVikingConfig] = None++ @classmethod+ def from_env(cls) -> "MemexConfig":+ """Create config from environment variables."""+ return cls(+ data_path=os.getenv("MEMEX_DATA_PATH", "./memex_data"),+ config_path=os.getenv("MEMEX_CONFIG_PATH", "./ov.conf"),+ user=os.getenv("MEMEX_USER", "default"),+ llm_temperature=float(os.getenv("MEMEX_LLM_TEMPERATURE", "0.7")),+ llm_max_tokens=int(os.getenv("MEMEX_LLM_MAX_TOKENS", "2048")),+ search_top_k=int(os.getenv("MEMEX_SEARCH_TOP_K", "5")),+ search_score_threshold=float(os.getenv("MEMEX_SEARCH_SCORE_THRESHOLD", "0.1")),+ )++ def get_openviking_config(self) -> OpenVikingConfig:+ """Load OpenViking config from ov.conf file."""+ if self._ov_config is not None:+ return self._ov_config++ config_file = Path(self.config_path)+ if not config_file.exists():+ raise FileNotFoundError(+ f"Config file not found: {self.config_path}\n"+ "Please copy ov.conf.example to ov.conf and configure your API keys."+ )++ with open(config_file, "r") as f:+ config_dict = json.load(f)++ self._ov_config = OpenVikingConfig.from_dict(config_dict)+ return self._ov_config++ def get_vlm_config(self) -> dict:+ """Get VLM config for RAG recipe."""+ ov_config = self.get_openviking_config()+ return {+ "api_base": ov_config.vlm.api_base,+ "api_key": ov_config.vlm.api_key,+ "model": ov_config.vlm.model,+ "backend": ov_config.vlm.backend,+ }diff --git a/examples/memex/feishu.py b/examples/memex/feishu.pynew file mode 100644index 000000000..ec2aa9692--- /dev/null+++ b/examples/memex/feishu.py@@ -0,0 +1,478 @@+"""+Feishu/Lark MCP integration for Memex.++This module provides integration with Feishu (Lark) through the official MCP server.+It allows importing documents, messages, and other content from Feishu into Memex.++Requirements:+- Node.js (for npx)+- Feishu App credentials (app_id, app_secret)++Usage:+ from memex.feishu import FeishuMCP++ feishu = FeishuMCP(app_id="cli_xxx", app_secret="xxx")+ feishu.start()++ # Read a document+ content = feishu.read_document(document_id="xxx")++ # Search documents+ results = feishu.search_documents(query="keyword")++ feishu.stop()+"""++import json+import os+import subprocess+import threading+import time+from dataclasses import dataclass+from typing import Any, Optional++from rich.console import Console+++@dataclass+class FeishuConfig:+ """Feishu MCP configuration."""++ app_id: str+ app_secret: str+ auth_mode: str = "tenant" # "tenant", "user", or "auto"+ tools: list[str] | None = None # Specific tools to enable, None for all++ @classmethod+ def from_env(cls) -> "FeishuConfig":+ """Create config from environment variables."""+ app_id = os.getenv("FEISHU_APP_ID") or os.getenv("LARK_APP_ID")+ app_secret = os.getenv("FEISHU_APP_SECRET") or os.getenv("LARK_APP_SECRET")++ if not app_id or not app_secret:+ raise ValueError(+ "Feishu credentials not found. Set FEISHU_APP_ID and FEISHU_APP_SECRET environment variables."+ )++ return cls(+ app_id=app_id,+ app_secret=app_secret,+ auth_mode=os.getenv("FEISHU_AUTH_MODE", "tenant"),+ )+++class FeishuMCPClient:+ """+ Feishu MCP Client - communicates with lark-openapi-mcp server.++ This client manages the MCP server process and provides methods to call+ Feishu APIs through the MCP protocol.+ """++ def __init__(self, config: Optional[FeishuConfig] = None, console: Optional[Console] = None):+ """Initialize Feishu MCP client.++ Args:+ config: Feishu configuration. If None, loads from environment.+ console: Rich console for output.+ """+ self.config = config or FeishuConfig.from_env()+ self.console = console or Console()+ self._process: Optional[subprocess.Popen] = None+ self._running = False++ def _build_command(self) -> list[str]:+ """Build the npx command to start the MCP server."""+ cmd = [+ "npx",+ "-y",+ "@larksuiteoapi/lark-mcp",+ "mcp",+ "-a",+ self.config.app_id,+ "-s",+ self.config.app_secret,+ ]++ # Add auth mode+ if self.config.auth_mode != "tenant":+ cmd.extend(["--auth-mode", self.config.auth_mode])++ # Add specific tools if configured+ if self.config.tools:+ for tool in self.config.tools:+ cmd.extend(["-t", tool])++ return cmd++ def start(self) -> bool:+ """Start the MCP server process.++ Returns:+ True if started successfully.+ """+ if self._running:+ self.console.print("[yellow]Feishu MCP server already running[/yellow]")+ return True++ try:+ cmd = self._build_command()+ self.console.print(f"[dim]Starting Feishu MCP server...[/dim]")++ # Start the process with stdio transport+ self._process = subprocess.Popen(+ cmd,+ stdin=subprocess.PIPE,+ stdout=subprocess.PIPE,+ stderr=subprocess.PIPE,+ text=True,+ bufsize=1,+ )++ # Give it a moment to start+ time.sleep(2)++ # Check if process is still running+ if self._process.poll() is not None:+ stderr = self._process.stderr.read() if self._process.stderr else ""+ self.console.print(f"[red]Failed to start Feishu MCP server: {stderr}[/red]")+ return False++ self._running = True+ self.console.print("[green]Feishu MCP server started[/green]")+ return True++ except FileNotFoundError:+ self.console.print("[red]npx not found. Please install Node.js.[/red]")+ return False+ except Exception as e:+ self.console.print(f"[red]Error starting Feishu MCP server: {e}[/red]")+ return False++ def stop(self) -> None:+ """Stop the MCP server process."""+ if self._process:+ self._process.terminate()+ try:+ self._process.wait(timeout=5)+ except subprocess.TimeoutExpired:+ self._process.kill()+ self._process = None+ self._running = False+ self.console.print("[dim]Feishu MCP server stopped[/dim]")++ def _send_request(self, method: str, params: dict[str, Any]) -> dict[str, Any]:+ """Send a JSON-RPC request to the MCP server.++ Args:+ method: MCP method name.+ params: Method parameters.++ Returns:+ Response from the server.+ """+ if not self._running or not self._process:+ raise RuntimeError("Feishu MCP server not running. Call start() first.")++ request = {+ "jsonrpc": "2.0",+ "id": 1,+ "method": method,+ "params": params,+ }++ try:+ # Send request+ self._process.stdin.write(json.dumps(request) + "\n")+ self._process.stdin.flush()++ # Read response+ response_line = self._process.stdout.readline()+ if response_line:+ return json.loads(response_line)+ else:+ raise RuntimeError("No response from MCP server")++ except Exception as e:+ raise RuntimeError(f"Error communicating with MCP server: {e}")++ def call_tool(self, tool_name: str, arguments: dict[str, Any]) -> Any:+ """Call a tool on the MCP server.++ Args:+ tool_name: Name of the tool to call.+ arguments: Tool arguments.++ Returns:+ Tool result.+ """+ response = self._send_request(+ "tools/call",+ {+ "name": tool_name,+ "arguments": arguments,+ },+ )++ if "error" in response:+ raise RuntimeError(f"Tool error: {response['error']}")++ return response.get("result", {})++ def list_tools(self) -> list[dict[str, Any]]:+ """List available tools.++ Returns:+ List of tool definitions.+ """+ response = self._send_request("tools/list", {})+ return response.get("result", {}).get("tools", [])++ # ==================== High-level API ====================++ def read_document(self, document_id: str) -> str:+ """Read a Feishu document.++ Args:+ document_id: Document ID (from URL or API).++ Returns:+ Document content as text.+ """+ result = self.call_tool(+ "docx.v1.document.rawContent",+ {+ "document_id": document_id,+ },+ )+ return result.get("content", "")++ def search_documents(self, query: str, count: int = 10) -> list[dict[str, Any]]:+ """Search Feishu documents.++ Args:+ query: Search query.+ count: Maximum number of results.++ Returns:+ List of search results.+ """+ result = self.call_tool(+ "docx.builtin.search",+ {+ "query": query,+ "count": count,+ },+ )+ return result.get("items", [])++ def list_messages(+ self,+ chat_id: str,+ start_time: Optional[str] = None,+ end_time: Optional[str] = None,+ page_size: int = 20,+ ) -> list[dict[str, Any]]:+ """List messages from a chat.++ Args:+ chat_id: Chat ID.+ start_time: Start time (Unix timestamp string).+ end_time: End time (Unix timestamp string).+ page_size: Number of messages per page.++ Returns:+ List of messages.+ """+ params = {+ "container_id_type": "chat",+ "container_id": chat_id,+ "page_size": page_size,+ }+ if start_time:+ params["start_time"] = start_time+ if end_time:+ params["end_time"] = end_time++ result = self.call_tool("im.v1.message.list", params)+ return result.get("items", [])++ def get_chat_info(self, chat_id: str) -> dict[str, Any]:+ """Get chat information.++ Args:+ chat_id: Chat ID.++ Returns:+ Chat information.+ """+ result = self.call_tool(+ "im.v1.chat.get",+ {+ "chat_id": chat_id,+ },+ )+ return result++ @property+ def is_running(self) -> bool:+ """Check if the MCP server is running."""+ return self._running+++class FeishuCommands:+ """Feishu commands for Memex CLI."""++ def __init__(self, client: "MemexClient", console: Console):+ """Initialize Feishu commands.++ Args:+ client: Memex client instance.+ console: Rich console for output.+ """+ from client import MemexClient++ self.memex_client = client+ self.console = console+ self._feishu: Optional[FeishuMCPClient] = None++ @property+ def feishu(self) -> FeishuMCPClient:+ """Get or create Feishu MCP client."""+ if self._feishu is None:+ try:+ self._feishu = FeishuMCPClient(console=self.console)+ except ValueError as e:+ self.console.print(f"[red]{e}[/red]")+ raise+ return self._feishu++ def connect(self) -> None:+ """Connect to Feishu MCP server."""+ try:+ if self.feishu.start():+ self.console.print("[green]Connected to Feishu[/green]")+ else:+ self.console.print("[red]Failed to connect to Feishu[/red]")+ except Exception as e:+ self.console.print(f"[red]Error: {e}[/red]")++ def disconnect(self) -> None:+ """Disconnect from Feishu MCP server."""+ if self._feishu:+ self._feishu.stop()+ self._feishu = None+ self.console.print("[dim]Disconnected from Feishu[/dim]")++ def import_document(self, document_id: str, target: Optional[str] = None) -> None:+ """Import a Feishu document into Memex.++ Args:+ document_id: Feishu document ID.+ target: Target URI in Memex.+ """+ if not document_id:+ self.console.print("[red]Usage: /feishu-doc <document_id>[/red]")+ return++ try:+ if not self.feishu.is_running:+ self.connect()++ self.console.print(f"[dim]Fetching document {document_id}...[/dim]")+ content = self.feishu.read_document(document_id)++ if content:+ # Save to a temporary file and add to Memex+ import tempfile++ with tempfile.NamedTemporaryFile(+ mode="w", suffix=".md", delete=False, prefix=f"feishu_{document_id}_"+ ) as f:+ f.write(content)+ temp_path = f.name++ # Add to Memex+ target = target or "viking://resources/feishu/documents/"+ self.memex_client.add_resource(+ path=temp_path,+ target=target,+ reason=f"Imported from Feishu document {document_id}",+ )++ # Clean up temp file+ os.unlink(temp_path)++ self.console.print(f"[green]✓ Imported document {document_id}[/green]")+ else:+ self.console.print(f"[yellow]Document {document_id} is empty[/yellow]")++ except Exception as e:+ self.console.print(f"[red]Error importing document: {e}[/red]")++ def search_and_import(self, query: str, count: int = 5) -> None:+ """Search Feishu documents and optionally import them.++ Args:+ query: Search query.+ count: Maximum number of results.+ """+ if not query:+ self.console.print("[red]Usage: /feishu-search <query>[/red]")+ return++ try:+ if not self.feishu.is_running:+ self.connect()++ self.console.print(f"[dim]Searching for '{query}'...[/dim]")+ results = self.feishu.search_documents(query, count)++ if not results:+ self.console.print(f"[dim]No documents found for '{query}'[/dim]")+ return++ from rich.table import Table++ table = Table(title=f"Feishu Documents: '{query}'", show_header=True)+ table.add_column("#", style="dim", width=3)+ table.add_column("Title", style="cyan")+ table.add_column("ID", style="dim")++ for i, doc in enumerate(results, 1):+ title = doc.get("title", "Untitled")+ doc_id = doc.get("id", "unknown")+ table.add_row(str(i), title, doc_id)++ self.console.print(table)+ self.console.print("[dim]Use /feishu-doc <id> to import a document[/dim]")++ except Exception as e:+ self.console.print(f"[red]Error searching: {e}[/red]")++ def list_tools(self) -> None:+ """List available Feishu MCP tools."""+ try:+ if not self.feishu.is_running:+ self.connect()++ tools = self.feishu.list_tools()++ from rich.table import Table++ table = Table(title="Available Feishu Tools", show_header=True)+ table.add_column("Tool", style="cyan")+ table.add_column("Description", style="white")++ for tool in tools[:20]: # Limit display+ name = tool.get("name", "unknown")+ desc = tool.get("description", "")[:60]+ table.add_row(name, desc)++ self.console.print(table)++ if len(tools) > 20:+ self.console.print(f"[dim]... and {len(tools) - 20} more tools[/dim]")++ except Exception as e:+ self.console.print(f"[red]Error listing tools: {e}[/red]")diff --git a/examples/memex/ov.conf.example b/examples/memex/ov.conf.examplenew file mode 100644index 000000000..d5187cd33--- /dev/null+++ b/examples/memex/ov.conf.example@@ -0,0 +1,17 @@+{+ "embedding": {+ "dense": {+ "api_base" : "https://ark.cn-beijing.volces.com/api/v3",+ "api_key" : "your-volcengine-api-key",+ "backend" : "volcengine",+ "dimension": "1024",+ "model" : "doubao-embedding-vision-250615"+ }+ },+ "vlm": {+ "api_base" : "https://ark.cn-beijing.volces.com/api/v3",+ "api_key" : "your-volcengine-api-key",+ "backend" : "volcengine",+ "model" : "doubao-seed-1-8-251228"+ }+}diff --git a/examples/memex/pyproject.toml b/examples/memex/pyproject.tomlnew file mode 100644index 000000000..ff18dcb1e--- /dev/null+++ b/examples/memex/pyproject.toml@@ -0,0 +1,15 @@+[project]+name = "memex"+version = "0.1.0"+description = "Personal Knowledge Assistant powered by OpenViking"+readme = "README.md"+requires-python = ">=3.13"+dependencies = [+ "openviking>=0.1.6",+ "prompt-toolkit>=3.0.52",+ "rich>=13.0.0",+ "openai>=1.0.0",+]++[project.scripts]+memex = "cli:main"diff --git a/examples/memex/rag/__init__.py b/examples/memex/rag/__init__.pynew file mode 100644index 000000000..cc5e3eeee--- /dev/null+++ b/examples/memex/rag/__init__.py@@ -0,0 +1,7 @@+"""+Memex RAG module.+"""++from .recipe import MemexRecipe++__all__ = ["MemexRecipe"]diff --git a/examples/memex/rag/recipe.py b/examples/memex/rag/recipe.pynew file mode 100644index 000000000..4826d5590--- /dev/null+++ b/examples/memex/rag/recipe.py@@ -0,0 +1,295 @@+"""+Memex RAG Recipe - RAG flow implementation for Memex.++Simplified design:+- OpenViking Session integration for context-aware search+- Automatic memory extraction via session.commit()+- Direct use of OpenViking score for ranking (no rerank)+- Unified content loading (no threshold-based truncation)+"""++from typing import Any, Optional++from openai import OpenAI++from client import MemexClient+from config import MemexConfig++try:+ from openviking.message import TextPart, ContextPart+except ImportError:+ TextPart = None+ ContextPart = None+++DEFAULT_SYSTEM_PROMPT = """You are Memex, a personal knowledge assistant.+You help users find and understand information from their personal knowledge base.++When answering questions:+1. Base your answers on the provided context from the knowledge base+2. If the context doesn't contain relevant information, say so clearly+3. Cite sources using [Source N] format when referencing information+4. Be concise but thorough++Context from knowledge base:+{context}+"""++NO_CONTEXT_PROMPT = """You are Memex, a personal knowledge assistant.+No relevant information was found in the knowledge base for this query.+Please let the user know and suggest they add relevant documents or rephrase their question.+"""+++class MemexRecipe:+ def __init__(+ self,+ client: MemexClient,+ config: Optional[MemexConfig] = None,+ ):+ self.client = client+ self.config = config or client.config+ self._llm_client: Optional[OpenAI] = None+ self._chat_history: list[dict[str, str]] = []+ self._vlm_config: Optional[dict] = None+ self._session = None++ def start_session(self, session_id: Optional[str] = None):+ self._session = self.client.get_session(session_id)+ if session_id:+ try:+ self._session.load()+ except Exception:+ pass+ return self._session++ def end_session(self) -> dict[str, Any]:+ if not self._session:+ return {"status": "no_session"}+ try:+ result = self._session.commit()+ # Wait for memory embedding to complete+ memories_extracted = result.get("memories_extracted", 0)+ if memories_extracted > 0:+ self.client.wait_processed()+ return result+ except Exception as e:+ return {"status": "error", "error": str(e)}++ @property+ def session(self):+ return self._session++ @property+ def session_id(self) -> Optional[str]:+ return self._session.session_id if self._session else None++ @property+ def vlm_config(self) -> dict:+ if self._vlm_config is None:+ self._vlm_config = self.config.get_vlm_config()+ return self._vlm_config++ @property+ def llm_client(self) -> OpenAI:+ if self._llm_client is None:+ vlm = self.vlm_config+ backend = vlm.get("backend", "openai")++ if backend == "openai":+ self._llm_client = OpenAI(+ api_key=vlm.get("api_key"),+ base_url=vlm.get("api_base") or "https://api.openai.com/v1",+ )+ elif backend == "volcengine":+ self._llm_client = OpenAI(+ api_key=vlm.get("api_key"),+ base_url=vlm.get("api_base") or "https://ark.cn-beijing.volces.com/api/v3",+ )+ else:+ raise ValueError(f"Unsupported LLM backend: {backend}")+ return self._llm_client++ @property+ def llm_model(self) -> str:+ return self.vlm_config.get("model", "gpt-4o-mini")++ def search(+ self,+ query: str,+ top_k: Optional[int] = None,+ target_uri: Optional[str] = None,+ score_threshold: Optional[float] = None,+ use_session: bool = True,+ ) -> list[dict[str, Any]]:+ top_k = top_k or self.config.search_top_k+ target_uri = target_uri or self.config.default_resource_uri+ score_threshold = score_threshold or self.config.search_score_threshold++ session_to_use = self._session if use_session else None++ results = self.client.search(+ query=query,+ target_uri=target_uri,+ top_k=top_k,+ score_threshold=score_threshold,+ session=session_to_use,+ )++ return self._process_search_results(results, top_k)++ def _process_search_results(self, results: Any, top_k: int) -> list[dict[str, Any]]:+ search_results = []++ all_items = []+ if hasattr(results, "resources"):+ all_items.extend(results.resources[:top_k])+ if hasattr(results, "memories"):+ all_items.extend(results.memories[:top_k])++ for r in all_items:+ try:+ uri = r.uri if hasattr(r, "uri") else str(r)+ score = r.score if hasattr(r, "score") else 0.0++ try:+ content = self.client.read(uri)+ content = content if content else ""+ except Exception as e:+ if "is a directory" in str(e):+ try:+ content = f"[Directory] {self.client.abstract(uri)}"+ except Exception:+ continue+ else:+ continue++ if content:+ search_results.append(+ {+ "uri": uri,+ "score": score,+ "content": content,+ }+ )+ except Exception:+ continue++ search_results.sort(key=lambda x: x["score"], reverse=True)+ return search_results++ def build_context(self, search_results: list[dict[str, Any]]) -> str:+ if not search_results:+ return ""++ context_parts = []+ for i, result in enumerate(search_results, 1):+ uri = result.get("uri", "unknown")+ content = result.get("content", "")+ score = result.get("score", 0.0)++ if not content:+ try:+ content = self.client.read(uri)+ except Exception:+ try:+ content = self.client.abstract(uri)+ except Exception:+ content = f"[Content from {uri}]"++ context_parts.append(f"[Source {i}] {uri} (score: {score:.2f})\n{content}")++ return "\n\n---\n\n".join(context_parts)++ def call_llm(+ self,+ messages: list[dict[str, str]],+ temperature: Optional[float] = None,+ max_tokens: Optional[int] = None,+ ) -> str:+ temperature = temperature if temperature is not None else self.config.llm_temperature+ max_tokens = max_tokens or self.config.llm_max_tokens++ response = self.llm_client.chat.completions.create(+ model=self.llm_model,+ messages=messages, # type: ignore+ temperature=temperature,+ max_tokens=max_tokens,+ )++ return response.choices[0].message.content or ""++ def query(+ self,+ user_query: str,+ search_top_k: Optional[int] = None,+ temperature: Optional[float] = None,+ max_tokens: Optional[int] = None,+ system_prompt: Optional[str] = None,+ score_threshold: Optional[float] = None,+ target_uri: Optional[str] = None,+ use_chat_history: bool = False,+ ) -> str:+ if self._session and TextPart:+ self._session.add_message("user", [TextPart(text=user_query)])++ search_results = self.search(+ query=user_query,+ top_k=search_top_k,+ target_uri=target_uri,+ score_threshold=score_threshold,+ use_session=True,+ )++ if self._session and ContextPart:+ for result in search_results[:3]:+ try:+ self._session.add_message(+ "assistant",+ [+ ContextPart(+ uri=result.get("uri", ""),+ context_type="resource",+ abstract=result.get("content", "")[:200],+ )+ ],+ )+ except Exception:+ pass++ context = self.build_context(search_results)++ if context:+ prompt = system_prompt or DEFAULT_SYSTEM_PROMPT+ formatted_prompt = prompt.format(context=context)+ else:+ formatted_prompt = NO_CONTEXT_PROMPT++ messages = [{"role": "system", "content": formatted_prompt}]++ if use_chat_history and self._chat_history:+ messages.extend(self._chat_history[-6:])++ messages.append({"role": "user", "content": user_query})++ response = self.call_llm(+ messages=messages,+ temperature=temperature,+ max_tokens=max_tokens,+ )++ if self._session and TextPart:+ self._session.add_message("assistant", [TextPart(text=response)])++ if use_chat_history:+ self._chat_history.append({"role": "user", "content": user_query})+ self._chat_history.append({"role": "assistant", "content": response})++ return response++ def clear_history(self) -> None:+ self._chat_history = []++ @property+ def chat_history(self) -> list[dict[str, str]]:+ return self._chat_history.copy()