kioku-agent-kit 0.2.0__tar.gz

kioku_agent_kit-0.2.0/.claude/settings.local.json

@@ -0,0 +1,22 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv *)",
+      "Bash(make *)",
+      "Bash(python *)",
+      "Bash(export *)",
+      "Bash(kioku *)",
+      "Bash(ls *)",
+      "Bash(which *)",
+      "Bash(cat *)",
+      "Bash(uv run:*)",
+      "Bash",
+      "Bash(uv build:*)",
+      "Bash(chmod:*)",
+      "Bash(docker build:*)",
+      "Bash(docker images:*)",
+      "Bash(docker run:*)",
+      "Bash(git status:*)"
+    ]
+  }
+}

kioku_agent_kit-0.2.0/.env.example

@@ -0,0 +1,26 @@
+# === Kioku Configuration ===
+# Copy this file to .env and fill in values
+
+# User context (multi-tenant isolation)
+# KIOKU_USER_ID=default
+
+# Paths
+KIOKU_MEMORY_DIR=~/.kioku/memory
+KIOKU_DATA_DIR=~/.kioku/data
+
+# ChromaDB
+# KIOKU_CHROMA_MODE=auto          # auto | server | embedded
+KIOKU_CHROMA_HOST=localhost
+KIOKU_CHROMA_PORT=8000
+# KIOKU_CHROMA_PERSIST_DIR=       # default: ~/.kioku/data/chroma (embedded mode)
+
+# FalkorDB (Knowledge Graph)
+KIOKU_FALKORDB_HOST=localhost
+KIOKU_FALKORDB_PORT=6379
+
+# Ollama (Embeddings)
+KIOKU_OLLAMA_HOST=http://localhost:11434
+KIOKU_OLLAMA_MODEL=nomic-embed-text
+
+# LLM (Entity Extraction)
+KIOKU_ANTHROPIC_API_KEY=

kioku_agent_kit-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+        extras: ["cli", "mcp", "full"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra ${{ matrix.extras }} --extra dev
+
+      - name: Lint
+        if: matrix.extras == 'full' && matrix.python-version == '3.12'
+        run: |
+          uv run ruff check src/ tests/
+          uv run ruff format --check src/ tests/
+
+      - name: Run integration tests
+        if: matrix.extras == 'full'
+        run: uv run python -m pytest tests/test_server.py -v
+
+      - name: Verify CLI import
+        if: matrix.extras == 'cli' || matrix.extras == 'full'
+        run: uv run kioku --help
+
+      - name: Verify MCP import
+        if: matrix.extras == 'mcp' || matrix.extras == 'full'
+        run: uv run python -c "from kioku.server import mcp; print(f'MCP server: {mcp.name}')"
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build wheel
+        run: uv build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

kioku_agent_kit-0.2.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environment
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Environment
+.env
+
+# Data (local only)
+*.db
+data/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Pytest
+.pytest_cache/
+
+# Ruff
+.ruff_cache/

kioku_agent_kit-0.2.0/CLAUDE.md

@@ -0,0 +1,28 @@
+# Kioku MCP — Claude Assistant Guide
+
+You are Claude Code, an AI agent working on the Kioku MCP server project. Your goal is to help implement feature restructuring and maintain code quality based on the requirements defined in the `docs` directory.
+
+## Current Primary Task: Refactoring & CLI Support
+The user might ask you to implement the phases outlined in `docs/06-restructure-plan.md`. 
+**CRITICAL:**
+1. **Always read `docs/06-restructure-plan.md`** first to understand the Phase and objective you are working on.
+2. Read `src/kioku/server.py` — this file currently contains ALL business logic, FastMCP decorators, and tool coordination, and needs to be carefully refactored without breaking any functionality.
+3. Be aware that the project uses 6 core tools: `save_memory`, `search_memories`, `recall_related`, `explain_connection`, `get_timeline`, and `list_memory_dates` (Note: `get_memories_by_date` and `get_life_patterns` were recently removed to adhere to the Minimalist architecture).
+
+## Codebase Context
+- Read `docs/01-requirements.md` and `docs/02-system-design.md` for architectural context.
+- We use a **Minimalist RAG Architecture**: `SQLite FTS5` for BM25, `ChromaDB` for Vector Search, and `FalkorDB` for GraphDB Traversal. 
+- Python 3.12 / 3.13 is used.
+- Dependencies are managed by `uv`. Use `uv add` to add packages.
+
+## Testing Strategy
+1. **Integration Tests (`tests/`)**: Run `make test` to execute fast integration tests using mocks (FakeEmbedder, InMemoryGraphStore). Tests must maintain 100% pass rate.
+2. **End-to-End Tests**: Run `export $(grep -v '^#' .env | xargs) && python tests/e2e_mcp_client.py`. This acts as a real MCP Client via stdio, executing all 6 tools, 2 resources, and 3 prompts against real Live DBs and Anthropic API. Ensure it passes without errors when logic is changed.
+   - **⚠️ CRITICAL DATA WARNING:** When running E2E tests, ensure that you use a separate mock user or mock tenant. **DO NOT** modify, pollute, or overwrite the real Telegram user's data (e.g., `~/.kioku/users/telegram/` or their sessions in `~/.openclaw`). All test data must be completely isolated.
+
+## Guidelines
+- Write strict type hints (`-> dict`, `-> list`, etc.).
+- Update integration tests in `/tests/` when modifying logic. Use `make test` to ensure 100% test pass.
+- **Graceful degradation is a must:** Missing databases (ChromaDB, FalkorDB) or missing LLM parameters should gracefully fallback (e.g., FakeEmbedder, InMemoryGraphStore) and never crash the CLI/MCP app.
+- Never write duplicate code logic. A `KiokuService` class should become the single source of truth for both MCP interfaces and future CLI interfaces.
+- Any modifications to terminal output logic for CLI should display properly in Vietnamese (`ensure_ascii=False` when printing JSON).

kioku_agent_kit-0.2.0/Dockerfile

@@ -0,0 +1,30 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install system deps
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy project files
+COPY pyproject.toml .
+COPY src/ src/
+
+# Install kioku with all extras
+RUN pip install --no-cache-dir ".[full]"
+
+# Create data directories
+RUN mkdir -p /data/memory /data/data
+
+ENV KIOKU_MEMORY_DIR=/data/memory \
+    KIOKU_DATA_DIR=/data/data \
+    KIOKU_CHROMA_MODE=auto
+
+COPY scripts/docker-entrypoint.sh /docker-entrypoint.sh
+RUN chmod +x /docker-entrypoint.sh
+
+ENTRYPOINT ["/docker-entrypoint.sh"]
+
+# Default: run MCP server via stdio
+CMD ["mcp"]

kioku_agent_kit-0.2.0/Makefile

@@ -0,0 +1,33 @@
+.PHONY: install dev test lint run clean
+
+install:
+	pip install -e ".[dev]"
+
+install-all:
+	pip install -e ".[all,dev]"
+
+dev:
+	python -m src.kioku.server
+
+test:
+	python -m pytest tests/ -v
+
+test-watch:
+	python -m pytest tests/ -v --tb=short -x
+
+lint:
+	ruff check src/ tests/
+	ruff format --check src/ tests/
+
+format:
+	ruff format src/ tests/
+
+docker-up:
+	docker compose up -d
+
+docker-down:
+	docker compose down
+
+clean:
+	rm -rf .pytest_cache __pycache__ src/**/__pycache__
+	find . -name "*.pyc" -delete

kioku_agent_kit-0.2.0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: kioku-agent-kit
+Version: 0.2.0
+Summary: Personal memory engine for AI agents — tri-hybrid search (BM25 + Vector + KG), CLI & MCP interfaces
+Project-URL: Homepage, https://github.com/phuc-nt/kioku-agent-kit
+Project-URL: Repository, https://github.com/phuc-nt/kioku-agent-kit
+Project-URL: Issues, https://github.com/phuc-nt/kioku-agent-kit/issues
+Author-email: Phúc Nguyễn <phucnt@example.com>
+License-Expression: MIT
+Keywords: agent,ai,claude,knowledge-graph,mcp,memory,rag
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: cli
+Requires-Dist: typer>=0.24.1; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: anthropic>=0.40; extra == 'full'
+Requires-Dist: chromadb>=0.6; extra == 'full'
+Requires-Dist: falkordb>=1.0; extra == 'full'
+Requires-Dist: fastmcp>=2.0.0; extra == 'full'
+Requires-Dist: ollama>=0.4; extra == 'full'
+Requires-Dist: typer>=0.24.1; extra == 'full'
+Provides-Extra: graph
+Requires-Dist: anthropic>=0.40; extra == 'graph'
+Requires-Dist: falkordb>=1.0; extra == 'graph'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=2.0.0; extra == 'mcp'
+Provides-Extra: vector
+Requires-Dist: chromadb>=0.6; extra == 'vector'
+Requires-Dist: ollama>=0.4; extra == 'vector'

kioku_agent_kit-0.2.0/README.md

@@ -0,0 +1,214 @@
+# Kioku Agent Kit
+
+**Kioku** (記憶 — *memory*) is a personal memory engine for AI agents. Save any thought, event, or feeling — Kioku stores it, understands context, and retrieves it via **tri-hybrid search** (BM25 + semantic vector + knowledge graph).
+
+```
+You → "Went to coffee with Mai, discussed the AI project"
+Kioku → saves to markdown + indexes BM25 + vector + knowledge graph
+You → "Who is Mai?" or "What did I discuss last week?"
+Kioku → traverses the graph, finds connections, returns evidence
+```
+
+Designed to be used by AI agents (OpenClaw, Claude Code, Cursor, etc.) as a long-term memory CLI tool — or as an MCP server for Claude Desktop.
+
+---
+
+## Quick Start
+
+### Option 1: CLI only (fastest, BM25 only)
+
+```bash
+pip install kioku-agent-kit[cli]
+kioku save "First memory — testing Kioku" --mood happy --tags test
+kioku search "test"
+```
+
+### Option 2: Full stack with Docker (recommended)
+
+```bash
+git clone https://github.com/phuc-nt/kioku-agent-kit.git && cd kioku-agent-kit
+cp .env.example .env  # add KIOKU_ANTHROPIC_API_KEY
+
+# Start databases (ChromaDB + FalkorDB + Ollama)
+docker compose up -d
+
+# Install with all features
+pip install -e ".[full]"
+
+# Test
+kioku save "Hello Kioku" --mood happy
+kioku search "hello"
+```
+
+### Option 3: MCP Server (for Claude Desktop / Cursor)
+
+```bash
+pip install kioku-agent-kit[mcp,vector,graph]
+python -m kioku.server
+```
+
+Add to `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "kioku": {
+      "command": "python",
+      "args": ["-m", "kioku.server"],
+      "env": { "KIOKU_USER_ID": "myproject" }
+    }
+  }
+}
+```
+
+### Option 4: Claude Code / Cursor (CLI agent mode)
+
+```bash
+pip install kioku-agent-kit[full]
+docker compose up -d
+export KIOKU_USER_ID=myproject
+export KIOKU_ANTHROPIC_API_KEY=sk-ant-...
+```
+
+Copy `skills/kioku/SKILL.md` to your project's skills directory — Claude Code will automatically discover and use Kioku for memory operations.
+
+---
+
+## Install Options
+
+| Command | What you get |
+|---|---|
+| `pip install kioku-agent-kit[cli]` | CLI + BM25 keyword search |
+| `pip install kioku-agent-kit[cli,vector]` | + semantic search (ChromaDB + Ollama) |
+| `pip install kioku-agent-kit[mcp]` | MCP server only |
+| `pip install kioku-agent-kit[full]` | Everything: CLI + MCP + vector + graph |
+
+---
+
+## CLI Commands
+
+| Command | Description | Example |
+|---|---|---|
+| `kioku save TEXT` | Save a memory | `kioku save "Lunch with Mai" --mood happy --tags food,friend` |
+| `kioku search QUERY` | Unified search (BM25 + vector + graph) | `kioku search "Mai AI project" --limit 10` |
+| `kioku entities` | Browse entity vocabulary | `kioku entities --limit 50` |
+| `kioku timeline` | Chronological entries | `kioku timeline --from 2026-02-01 --to 2026-02-28` |
+
+`search` automatically extracts entities from the query using LLM + canonical entity vocabulary. Pass `--entities "X,Y"` to override.
+
+**Environment:**
+```bash
+KIOKU_USER_ID=myproject          # data isolation key (default: default)
+KIOKU_ANTHROPIC_API_KEY=sk-ant-  # for entity extraction (optional — degrades gracefully)
+KIOKU_OLLAMA_MODEL=bge-m3        # embedding model (default: bge-m3)
+```
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Interface Layer                       │
+│                                                         │
+│   server.py (MCP)           cli.py (Typer CLI)          │
+│   @mcp.tool()               @app.command()              │
+│         │                         │                     │
+│         └───────────┬─────────────┘                     │
+│                     ▼                                   │
+│           service.py (KiokuService)                     │
+│                     │                                   │
+│        ┌────────────┼────────────┐                      │
+│        ▼            ▼            ▼                      │
+│   pipeline/     search/      storage/                   │
+│  (indexing)   (retrieval)   (markdown)                  │
+│        │            │            │                      │
+│        ▼            ▼            ▼                      │
+│   ChromaDB     FalkorDB     SQLite FTS5                │
+│   (vector)     (graph)      (keyword)                   │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Search pipeline:** BM25 + Vector + Graph → RRF rerank → Graph context enrichment → Results with evidence
+
+**Save pipeline:** Markdown → SQLite FTS5 → ChromaDB embedding → FalkorDB entity/relationship graph
+
+---
+
+## MCP Interface (for Claude Desktop)
+
+**4 Tools:** `save_memory`, `search_memories`, `list_entities`, `get_timeline`
+
+**2 Resources:** `kioku://memories/{date}`, `kioku://entities/{entity}`
+
+**3 Prompts:** `reflect_on_day`, `analyze_relationships`, `weekly_review`
+
+---
+
+## Docker
+
+```bash
+# Full: Kioku + ChromaDB + FalkorDB + Ollama
+docker compose up -d
+
+# Minimal: no graph DB
+docker compose -f docker-compose.minimal.yml up -d
+
+# Use CLI inside container
+docker compose exec kioku kioku search "test"
+```
+
+---
+
+## Graceful Degradation
+
+| Missing | Fallback |
+|---|---|
+| Ollama / ChromaDB | Fake embeddings (BM25 still works) |
+| FalkorDB | InMemoryGraphStore (search still works) |
+| Anthropic API key | No auto entity extraction (pass `--entities` manually) |
+
+Kioku never crashes on missing infrastructure — it just skips the unavailable component.
+
+---
+
+## Tech Stack
+
+| Component | Technology |
+|---|---|
+| Core | Python 3.12+ / Pydantic |
+| CLI | Typer |
+| MCP Server | FastMCP |
+| Vector DB | ChromaDB |
+| Graph DB | FalkorDB |
+| Keyword Index | SQLite FTS5 |
+| Embedding | Ollama (`bge-m3`) |
+| Entity Extraction | Claude Haiku 4.5 (Anthropic API) |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/phuc-nt/kioku-agent-kit.git && cd kioku-agent-kit
+pip install -e ".[full,dev]"
+docker compose up -d
+
+uv run pytest tests/ -v           # unit tests (mocked DBs)
+python tests/e2e_mcp_client.py    # MCP E2E (real DBs)
+python tests/e2e_cli.py           # CLI E2E (real DBs)
+make lint                         # ruff check + format
+```
+
+---
+
+## Docs
+
+- [System Architecture](docs/architecture/system.md)
+- [Search Architecture](docs/architecture/search.md)
+- [Save Architecture](docs/architecture/save.md)
+
+---
+
+## License
+
+MIT

kioku_agent_kit-0.2.0/docker-compose.full.yml

@@ -0,0 +1,55 @@
+# Kioku Full Stack — Kioku + ChromaDB server + FalkorDB + Ollama
+# All features enabled: BM25 + Vector Search + Knowledge Graph
+#
+# Usage: docker compose -f docker-compose.full.yml up -d
+
+services:
+  kioku:
+    build: .
+    volumes:
+      - kioku_data:/data
+    environment:
+      - KIOKU_CHROMA_MODE=server
+      - KIOKU_CHROMA_HOST=chromadb
+      - KIOKU_CHROMA_PORT=8000
+      - KIOKU_FALKORDB_HOST=falkordb
+      - KIOKU_FALKORDB_PORT=6379
+      - KIOKU_OLLAMA_HOST=http://ollama:11434
+      - KIOKU_OLLAMA_MODEL=nomic-embed-text
+      - KIOKU_ANTHROPIC_API_KEY=${KIOKU_ANTHROPIC_API_KEY:-}
+    depends_on:
+      - chromadb
+      - falkordb
+      - ollama
+
+  chromadb:
+    image: chromadb/chroma:latest
+    ports:
+      - "8000:8000"
+    volumes:
+      - chroma_data:/chroma/chroma
+    environment:
+      - ANONYMIZED_TELEMETRY=false
+    restart: unless-stopped
+
+  falkordb:
+    image: falkordb/falkordb:latest
+    ports:
+      - "6379:6379"
+    volumes:
+      - falkordb_data:/data
+    restart: unless-stopped
+
+  ollama:
+    image: ollama/ollama:latest
+    ports:
+      - "11434:11434"
+    volumes:
+      - ollama_data:/root/.ollama
+    restart: unless-stopped
+
+volumes:
+  kioku_data:
+  chroma_data:
+  falkordb_data:
+  ollama_data:

kioku_agent_kit-0.2.0/docker-compose.minimal.yml

@@ -0,0 +1,30 @@
+# Kioku Minimal Stack — Kioku + Ollama only
+# ChromaDB runs in embedded mode, no FalkorDB (graph features disabled)
+#
+# Usage: docker compose -f docker-compose.minimal.yml up -d
+
+services:
+  kioku:
+    build: .
+    volumes:
+      - kioku_data:/data
+    environment:
+      - KIOKU_CHROMA_MODE=embedded
+      - KIOKU_OLLAMA_HOST=http://ollama:11434
+      - KIOKU_OLLAMA_MODEL=nomic-embed-text
+    depends_on:
+      - ollama
+    # Default CMD is "mcp" — override for CLI:
+    # docker compose -f docker-compose.minimal.yml exec kioku kioku search "test"
+
+  ollama:
+    image: ollama/ollama:latest
+    ports:
+      - "11434:11434"
+    volumes:
+      - ollama_data:/root/.ollama
+    restart: unless-stopped
+
+volumes:
+  kioku_data:
+  ollama_data:

kioku_agent_kit-0.2.0/docker-compose.yml

@@ -0,0 +1,31 @@
+services:
+  falkordb:
+    image: falkordb/falkordb:latest
+    ports:
+      - "6379:6379"
+    volumes:
+      - falkordb_data:/data
+    restart: unless-stopped
+
+  chromadb:
+    image: chromadb/chroma:latest
+    ports:
+      - "8000:8000"
+    volumes:
+      - chroma_data:/chroma/chroma
+    environment:
+      - ANONYMIZED_TELEMETRY=false
+    restart: unless-stopped
+
+  ollama:
+    image: ollama/ollama:latest
+    ports:
+      - "11434:11434"
+    volumes:
+      - ollama_data:/root/.ollama
+    restart: unless-stopped
+
+volumes:
+  falkordb_data:
+  chroma_data:
+  ollama_data:

kioku_agent_kit-0.2.0/docs/01-requirements.md

@@ -0,0 +1,52 @@
+# Kioku MCP Server — Requirements
+
+## Mục tiêu
+
+Kioku là một MCP Server đóng vai trợ lý lưu trữ ký ức cá nhân (diary/lifelog). Người dùng nhắn bất kỳ suy nghĩ, sự kiện, cảm xúc nào → Kioku lưu trữ, hiểu ngữ nghĩa, và có thể truy vấn lại theo **ý nghĩa sâu** — giúp người dùng lý giải bản thân và không bao giờ quên các ký ức quan trọng.
+
+## Functional Requirements
+
+### FR1 — Lưu trữ ký ức (Save)
+- Nhận đầu vào là text tự do (không cần format)
+- Tự động gắn timestamp, extract entities (người, nơi chốn, cảm xúc, sự kiện)
+- Lưu raw text vào Markdown file (source of truth)
+- Index song song vào Vector DB, Graph DB, Keyword Index
+
+### FR2 — Tìm kiếm Tri-hybrid (Search)
+- **Keyword Search (BM25):** Tìm chính xác theo từ khóa
+- **Vector Search (Semantic):** Tìm theo ý nghĩa tương đồng
+- **Graph Search (GraphRAG):** Tìm theo chuỗi liên kết nhân-quả, thời gian, cảm xúc
+- Kết hợp 3 kết quả bằng RRF (Reciprocal Rank Fusion) reranker
+
+### FR3 — Truy vấn liên kết (Recall & Explain)
+- Từ một entity, đi dọc theo graph edges để tìm các sự kiện liên quan
+- Giải thích mối liên hệ giữa 2 sự kiện/thực thể bất kỳ
+
+### FR4 — Xem lại ký ức (Browse)
+- Xem timeline các sự kiện trong khoảng thời gian theo thứ tự thời gian
+- Xem danh sách các ngày đã ghi chú nhật ký
+- Lấy danh sách entities hoặc thống kê cơ bản thông qua MCP resources
+
+### FR5 — Prompt Templates
+- `reflect_on_day`: Hồi tưởng cuối ngày
+- `weekly_review`: Tổng kết tuần
+- `find_why`: Truy vấn nguyên nhân cảm xúc/hành vi
+
+## Non-Functional Requirements
+
+| Yêu cầu | Mục tiêu |
+|---|---|
+| **Privacy** | 100% local, không gửi dữ liệu lên cloud (trừ LLM API calls) |
+| **Latency** | Search < 2s, Save < 3s (bao gồm extraction) |
+| **Portability** | MCP protocol → dùng được với OpenClaw, Claude Desktop, Cursor |
+| **Durability** | Markdown = source of truth; Graph/Vector chỉ là derived index, rebuild được |
+| **Deployment** | Docker Compose cho toàn bộ stack, chạy trên Mac Mini |
+
+## Constraints
+
+- Graph DB: **FalkorDB** (Docker container)
+- Vector DB: **ChromaDB** (embedded hoặc Docker)
+- Keyword Index: **SQLite FTS5** (file-based, trong container MCP server)
+- Embedding: Local via **Ollama** hoặc API (Anthropic/OpenAI)
+- Entity Extraction LLM: **Claude Haiku 4.5** via Anthropic API
+- MCP Server: **Python + FastMCP**, chạy local