Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

Feature/new demo (#78)

Allend101fac8ec1a
diff --git a/examples/memex/.gitignore b/examples/memex/.gitignore
new file mode 100644
index 000000000..bda059da6
--- /dev/null
+++ b/examples/memex/.gitignore
@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+data/
+uv.lock
+ov.conf
diff --git a/examples/memex/README.md b/examples/memex/README.md
new file mode 100644
index 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__.py
new file mode 100644
index 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 stats
diff --git a/examples/memex/commands/__init__.py b/examples/memex/commands/__init__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.example
new file mode 100644
index 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.toml
new file mode 100644
index 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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()