transcendence-memory-server 0.3.0__tar.gz

transcendence_memory_server-0.3.0/.env.example

@@ -0,0 +1,47 @@
+# transcendence-memory-server 环境变量模板
+# 复制为 .env 并填入实际值：cp .env.example .env
+
+# ╔═══════════════════════════════════════════════════════╗
+# ║  必需配置（基础 LanceDB 向量检索）                       ║
+# ╚═══════════════════════════════════════════════════════╝
+
+# 服务端 API 认证密钥（客户端通过 X-API-KEY 或 Authorization: Bearer 传入）
+RAG_API_KEY=your-rag-api-key
+
+# Embedding 模型配置
+EMBEDDING_BASE_URL=https://api.openai.com/v1
+EMBEDDING_API_KEY=sk-your-api-key
+EMBEDDING_MODEL=gemini-embedding-001
+EMBEDDING_DIM=3072
+
+# ╔═══════════════════════════════════════════════════════╗
+# ║  可选：启用 LightRAG 知识图谱                           ║
+# ║  设置后架构升级为 lancedb+lightrag                      ║
+# ╚═══════════════════════════════════════════════════════╝
+
+LLM_MODEL=gemini-2.5-flash
+LLM_BASE_URL=https://api.openai.com/v1
+LLM_API_KEY=sk-your-api-key
+
+# ╔═══════════════════════════════════════════════════════╗
+# ║  可选：启用多模态 RAG（PDF/图片/表格解析）                ║
+# ║  需同时配置上方 LLM 密钥                                ║
+# ║  设置后架构升级为 rag-everything                        ║
+# ╚═══════════════════════════════════════════════════════╝
+
+VLM_MODEL=qwen3-vl-plus
+VLM_BASE_URL=https://api.openai.com/v1
+VLM_API_KEY=sk-your-api-key
+
+# ╔═══════════════════════════════════════════════════════╗
+# ║  服务配置                                              ║
+# ╚═══════════════════════════════════════════════════════╝
+
+# 对外 endpoint（connection token 中使用）
+RAG_ADVERTISED_ENDPOINT=http://localhost:8711
+
+# 工作区目录（Docker 中默认 /data，本地开发使用项目根目录）
+WORKSPACE=/data
+
+# 端口（仅 docker-compose 使用）
+TM_PORT=8711

transcendence_memory_server-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI/CD
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*.*.*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest tests/ -v
+
+  publish-pypi:
+    needs: test
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build and publish
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          pip install build twine
+          python -m build
+          twine upload dist/*
+
+  publish-docker:
+    needs: test
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ secrets.DOCKERHUB_USERNAME }}/transcendence-memory-server
+          tags: |
+            type=semver,pattern={{version}}
+            type=raw,value=latest
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

transcendence_memory_server-0.3.0/.gitignore

@@ -0,0 +1,48 @@
+__pycache__/
+.pytest_cache/
+.learnings/
+.venv-task-rag-server/
+.venv/
+venv/
+scripts/__pycache__/
+tests/__pycache__/
+
+# LightRAG runtime data
+kv_store_*.json
+vdb_*.json
+graph_chunk_entity_relation.graphml
+
+# Runtime data
+tasks/rag/containers/
+memory/
+memory_archive/
+
+# Environment
+.env
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+src/*.egg-info/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Coverage
+htmlcov/
+.coverage
+coverage.xml
+
+# Secrets (defensive)
+.env.*
+!.env.example
+*.pem
+*.key

transcendence_memory_server-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing
+
+Thanks for your interest in contributing to transcendence-memory-server!
+
+## Development Setup
+
+```bash
+git clone https://github.com/leekkk2/transcendence-memory-server.git
+cd transcendence-memory-server
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+pytest tests/ -v
+```
+
+## Code Style
+
+- Python 3.11+, type hints encouraged
+- Keep functions under 50 lines
+- Use meaningful names, avoid magic numbers
+
+## Pull Requests
+
+1. Fork the repo and create a feature branch
+2. Write tests for new functionality
+3. Ensure all tests pass
+4. Submit a PR with a clear description
+
+## Reporting Issues
+
+Use [GitHub Issues](https://github.com/leekkk2/transcendence-memory-server/issues) with:
+- Steps to reproduce
+- Expected vs actual behavior
+- Environment details (OS, Python version, Docker version)
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

transcendence_memory_server-0.3.0/Dockerfile

@@ -0,0 +1,21 @@
+FROM python:3.13-slim AS builder
+WORKDIR /build
+RUN pip install --no-cache-dir \
+    fastapi uvicorn httpx requests numpy \
+    lancedb pyarrow lightrag-hku
+# raganything 从 GitHub 安装（可选，失败不阻塞构建）
+RUN pip install --no-cache-dir git+https://github.com/HKUDS/RAG-Anything.git || true
+
+FROM python:3.13-slim
+RUN apt-get update && apt-get install -y --no-install-recommends curl && rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+COPY --from=builder /usr/local/lib/python3.13/site-packages /usr/local/lib/python3.13/site-packages
+COPY --from=builder /usr/local/bin /usr/local/bin
+COPY scripts/ ./scripts/
+COPY src/ ./src/
+RUN chmod +x /app/scripts/entrypoint.sh
+RUN mkdir -p /data/tasks/active /data/tasks/archived /data/tasks/rag/containers /data/memory /data/memory_archive
+ENV WORKSPACE=/data
+EXPOSE 8711
+HEALTHCHECK --interval=30s --timeout=10s --retries=3 --start-period=15s CMD curl -f http://localhost:8711/health || exit 1
+ENTRYPOINT ["/app/scripts/entrypoint.sh"]

transcendence_memory_server-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 leekkk2
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

transcendence_memory_server-0.3.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: transcendence-memory-server
+Version: 0.3.0
+Summary: Self-hosted multimodal RAG memory service with LanceDB + RAG-Anything
+Project-URL: Homepage, https://github.com/leekkk2/transcendence-memory-server
+Project-URL: Repository, https://github.com/leekkk2/transcendence-memory-server
+Project-URL: Issues, https://github.com/leekkk2/transcendence-memory-server/issues
+Author: leekkk2
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fastapi,lancedb,lightrag,memory,multimodal,rag,vector-database
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.11
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: lancedb>=0.4.0
+Requires-Dist: lightrag-hku>=1.4.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pyarrow>=12.0.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: uvicorn>=0.20.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Provides-Extra: multimodal
+Requires-Dist: raganything>=1.2.0; extra == 'multimodal'
+Description-Content-Type: text/markdown
+
+# Transcendence Memory Server
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](Dockerfile)
+
+> **Self-hosted multimodal RAG cloud memory service — a shared brain for your AI agents.**
+
+[中文文档](README.zh-CN.md)
+
+Transcendence Memory Server is a cloud memory backend that multiple AI agents connect to simultaneously. Each agent stores its own memories in isolated containers, while being able to cross-query other agents' knowledge — turning isolated AI sessions into a collaborative, persistent knowledge network.
+
+```
+  Agent A (Claude Code)          Agent B (Codex CLI)          Agent C (OpenClaw)
+       |                              |                              |
+       |  store & search own          |  store & search own          |  store & search own
+       |  cross-query B, C            |  cross-query A, C            |  cross-query A, B
+       |                              |                              |
+       +------------------------------+------------------------------+
+                                      |
+                         Transcendence Memory Server
+                         +-------------------------+
+                         |  Container: agent-a      |
+                         |  Container: agent-b      |
+                         |  Container: agent-c      |
+                         |  Container: shared       |
+                         +-------------------------+
+```
+
+## Why Cloud Memory?
+
+| Problem | Without | With Transcendence |
+|---------|---------|-------------------|
+| Session ends | Memory lost | Persisted to cloud, recoverable anytime |
+| Switch agents | Start from zero | New agent inherits context via search |
+| Cross-project | Knowledge siloed | Agent B queries Agent A's decisions |
+| Team of agents | Each works in isolation | Shared container for collective knowledge |
+| Onboarding | Re-explain everything | Agent reads past decisions and rationale |
+
+## Features
+
+- **Multi-Agent Cloud Memory** — one server, many agents; each stores its own, each can query others
+- **Container Isolation** — per-agent or per-project namespaces with full CRUD; shared containers for team knowledge
+- **LanceDB Vector Search** — sub-second semantic retrieval over task cards, memory objects, and structured data
+- **LightRAG Knowledge Graph** — entity/relation extraction with hybrid retrieval (local + global + keyword)
+- **RAG-Anything Multimodal** — PDF, image, and table parsing with vision model support
+- **Auto-Detect Architecture** — automatically enables capabilities based on configured API keys
+- **Connection Token** — one-step client setup; give each agent a token and it's connected
+- **Zero Permission Issues** — Docker named volumes, no bind mount headaches
+
+## Architecture Tiers
+
+The server auto-detects its capability tier based on your `.env` configuration:
+
+| Tier | Required Keys | Capabilities |
+|------|--------------|-------------|
+| `lancedb-only` | `EMBEDDING_API_KEY` | Vector search, typed objects, structured ingest |
+| `lancedb+lightrag` | + `LLM_API_KEY` | + Knowledge graph, entity extraction, hybrid queries |
+| `rag-everything` | + `VLM_API_KEY` | + PDF/image/table parsing, vision model queries |
+
+## Quick Start
+
+### Docker (recommended)
+
+```bash
+git clone https://github.com/leekkk2/transcendence-memory-server.git
+cd transcendence-memory-server
+cp .env.example .env    # edit with your API keys
+docker compose up -d --build
+curl http://localhost:8711/health
+```
+
+### Production (VPS + Nginx)
+
+```bash
+# Preflight check
+bash scripts/preflight_check.sh
+
+# Deploy with localhost-only binding
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build
+```
+
+### Connect Your Agents
+
+Once the server is running, each agent gets its own connection token:
+
+```bash
+# Export a token for Agent A
+curl -sS "http://localhost:8711/export-connection-token?container=agent-a" \
+  -H "X-API-KEY: your-key"
+
+# Export a token for Agent B (different container)
+curl -sS "http://localhost:8711/export-connection-token?container=agent-b" \
+  -H "X-API-KEY: your-key"
+
+# Export a shared container token (for cross-agent collaboration)
+curl -sS "http://localhost:8711/export-connection-token?container=shared" \
+  -H "X-API-KEY: your-key"
+```
+
+Give each token to the corresponding agent. With the [transcendence-memory](https://github.com/leekkk2/transcendence-memory) skill installed, the agent runs `/tm connect <token>` and it's ready.
+
+### Local Development
+
+```bash
+./scripts/bootstrap_dev.sh
+export RAG_API_KEY="your-key"
+export EMBEDDING_API_KEY="your-key"
+./scripts/run_task_rag_server.sh
+```
+
+## API Overview
+
+### Text Memory (Lightweight Path)
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check with module status (public) |
+| `/search` | POST | Semantic vector search |
+| `/embed` | POST | Rebuild LanceDB index |
+| `/ingest-memory/objects` | POST | Store typed memory objects |
+| `/ingest-structured` | POST | Structured JSON ingest |
+| `/containers/{c}/memories/{id}` | PUT/DELETE | Update/delete individual memories |
+
+### Multimodal RAG (Knowledge Graph Path)
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/documents/text` | POST | Ingest text into knowledge graph |
+| `/documents/upload` | POST | Upload PDF/image/MD files |
+| `/query` | POST | RAG query with LLM-generated answer |
+
+### Management
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/containers` | GET | List all containers |
+| `/containers/{name}` | DELETE | Delete a container |
+| `/export-connection-token` | GET | Export credentials for client setup |
+| `/jobs/{pid}` | GET | Check async task status |
+
+All endpoints except `/health` require authentication via `X-API-KEY` or `Authorization: Bearer` header.
+
+## Configuration
+
+All settings via `.env` file (see [.env.example](.env.example)):
+
+| Variable | Required | Tier | Description |
+|----------|----------|------|-------------|
+| `RAG_API_KEY` | Yes | All | API authentication key |
+| `EMBEDDING_API_KEY` | Yes | All | Embedding model API key |
+| `EMBEDDING_BASE_URL` | No | All | Embedding endpoint (default: OpenAI) |
+| `EMBEDDING_MODEL` | No | All | Model name (default: gemini-embedding-001) |
+| `LLM_API_KEY` | No | lightrag+ | LLM API key for knowledge graph |
+| `LLM_MODEL` | No | lightrag+ | LLM model (default: gemini-2.5-flash) |
+| `VLM_API_KEY` | No | everything | Vision model API key |
+| `VLM_MODEL` | No | everything | Vision model (default: qwen3-vl-plus) |
+
+## CLI
+
+```bash
+pip install -e .
+tm-server start              # Start server (default 0.0.0.0:8711)
+tm-server start --port 9000  # Custom port
+tm-server health             # Health check
+tm-server export-token       # Export connection token
+```
+
+## Client Skill
+
+Pair with [transcendence-memory](https://github.com/leekkk2/transcendence-memory) — an agent skill that provides built-in commands (`/tm connect`, `/tm search`, `/tm remember`, `/tm query`) for Claude Code, OpenClaw, Codex CLI, and other AI coding agents.
+
+## Documentation
+
+- [Quick Start](docs/deployment/quickstart.md)
+- [Docker Deployment](docs/deployment/docker-deployment.md)
+- [Reverse Proxy](docs/deployment/reverse-proxy.md)
+- [Environment Reference](docs/deployment/environment-reference.md)
+- [API Contract](docs/api-contract.md)
+- [Health Check](docs/operations/health-check.md)
+- [Troubleshooting](docs/operations/troubleshooting.md)
+- [Development Bootstrap](docs/development-bootstrap.md)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Pull requests welcome.
+
+## License
+
+[MIT](LICENSE)

transcendence_memory_server-0.3.0/README.md

@@ -0,0 +1,190 @@
+# Transcendence Memory Server
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](Dockerfile)
+
+> **Self-hosted multimodal RAG cloud memory service — a shared brain for your AI agents.**
+
+[中文文档](README.zh-CN.md)
+
+Transcendence Memory Server is a cloud memory backend that multiple AI agents connect to simultaneously. Each agent stores its own memories in isolated containers, while being able to cross-query other agents' knowledge — turning isolated AI sessions into a collaborative, persistent knowledge network.
+
+```
+  Agent A (Claude Code)          Agent B (Codex CLI)          Agent C (OpenClaw)
+       |                              |                              |
+       |  store & search own          |  store & search own          |  store & search own
+       |  cross-query B, C            |  cross-query A, C            |  cross-query A, B
+       |                              |                              |
+       +------------------------------+------------------------------+
+                                      |
+                         Transcendence Memory Server
+                         +-------------------------+
+                         |  Container: agent-a      |
+                         |  Container: agent-b      |
+                         |  Container: agent-c      |
+                         |  Container: shared       |
+                         +-------------------------+
+```
+
+## Why Cloud Memory?
+
+| Problem | Without | With Transcendence |
+|---------|---------|-------------------|
+| Session ends | Memory lost | Persisted to cloud, recoverable anytime |
+| Switch agents | Start from zero | New agent inherits context via search |
+| Cross-project | Knowledge siloed | Agent B queries Agent A's decisions |
+| Team of agents | Each works in isolation | Shared container for collective knowledge |
+| Onboarding | Re-explain everything | Agent reads past decisions and rationale |
+
+## Features
+
+- **Multi-Agent Cloud Memory** — one server, many agents; each stores its own, each can query others
+- **Container Isolation** — per-agent or per-project namespaces with full CRUD; shared containers for team knowledge
+- **LanceDB Vector Search** — sub-second semantic retrieval over task cards, memory objects, and structured data
+- **LightRAG Knowledge Graph** — entity/relation extraction with hybrid retrieval (local + global + keyword)
+- **RAG-Anything Multimodal** — PDF, image, and table parsing with vision model support
+- **Auto-Detect Architecture** — automatically enables capabilities based on configured API keys
+- **Connection Token** — one-step client setup; give each agent a token and it's connected
+- **Zero Permission Issues** — Docker named volumes, no bind mount headaches
+
+## Architecture Tiers
+
+The server auto-detects its capability tier based on your `.env` configuration:
+
+| Tier | Required Keys | Capabilities |
+|------|--------------|-------------|
+| `lancedb-only` | `EMBEDDING_API_KEY` | Vector search, typed objects, structured ingest |
+| `lancedb+lightrag` | + `LLM_API_KEY` | + Knowledge graph, entity extraction, hybrid queries |
+| `rag-everything` | + `VLM_API_KEY` | + PDF/image/table parsing, vision model queries |
+
+## Quick Start
+
+### Docker (recommended)
+
+```bash
+git clone https://github.com/leekkk2/transcendence-memory-server.git
+cd transcendence-memory-server
+cp .env.example .env    # edit with your API keys
+docker compose up -d --build
+curl http://localhost:8711/health
+```
+
+### Production (VPS + Nginx)
+
+```bash
+# Preflight check
+bash scripts/preflight_check.sh
+
+# Deploy with localhost-only binding
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build
+```
+
+### Connect Your Agents
+
+Once the server is running, each agent gets its own connection token:
+
+```bash
+# Export a token for Agent A
+curl -sS "http://localhost:8711/export-connection-token?container=agent-a" \
+  -H "X-API-KEY: your-key"
+
+# Export a token for Agent B (different container)
+curl -sS "http://localhost:8711/export-connection-token?container=agent-b" \
+  -H "X-API-KEY: your-key"
+
+# Export a shared container token (for cross-agent collaboration)
+curl -sS "http://localhost:8711/export-connection-token?container=shared" \
+  -H "X-API-KEY: your-key"
+```
+
+Give each token to the corresponding agent. With the [transcendence-memory](https://github.com/leekkk2/transcendence-memory) skill installed, the agent runs `/tm connect <token>` and it's ready.
+
+### Local Development
+
+```bash
+./scripts/bootstrap_dev.sh
+export RAG_API_KEY="your-key"
+export EMBEDDING_API_KEY="your-key"
+./scripts/run_task_rag_server.sh
+```
+
+## API Overview
+
+### Text Memory (Lightweight Path)
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check with module status (public) |
+| `/search` | POST | Semantic vector search |
+| `/embed` | POST | Rebuild LanceDB index |
+| `/ingest-memory/objects` | POST | Store typed memory objects |
+| `/ingest-structured` | POST | Structured JSON ingest |
+| `/containers/{c}/memories/{id}` | PUT/DELETE | Update/delete individual memories |
+
+### Multimodal RAG (Knowledge Graph Path)
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/documents/text` | POST | Ingest text into knowledge graph |
+| `/documents/upload` | POST | Upload PDF/image/MD files |
+| `/query` | POST | RAG query with LLM-generated answer |
+
+### Management
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/containers` | GET | List all containers |
+| `/containers/{name}` | DELETE | Delete a container |
+| `/export-connection-token` | GET | Export credentials for client setup |
+| `/jobs/{pid}` | GET | Check async task status |
+
+All endpoints except `/health` require authentication via `X-API-KEY` or `Authorization: Bearer` header.
+
+## Configuration
+
+All settings via `.env` file (see [.env.example](.env.example)):
+
+| Variable | Required | Tier | Description |
+|----------|----------|------|-------------|
+| `RAG_API_KEY` | Yes | All | API authentication key |
+| `EMBEDDING_API_KEY` | Yes | All | Embedding model API key |
+| `EMBEDDING_BASE_URL` | No | All | Embedding endpoint (default: OpenAI) |
+| `EMBEDDING_MODEL` | No | All | Model name (default: gemini-embedding-001) |
+| `LLM_API_KEY` | No | lightrag+ | LLM API key for knowledge graph |
+| `LLM_MODEL` | No | lightrag+ | LLM model (default: gemini-2.5-flash) |
+| `VLM_API_KEY` | No | everything | Vision model API key |
+| `VLM_MODEL` | No | everything | Vision model (default: qwen3-vl-plus) |
+
+## CLI
+
+```bash
+pip install -e .
+tm-server start              # Start server (default 0.0.0.0:8711)
+tm-server start --port 9000  # Custom port
+tm-server health             # Health check
+tm-server export-token       # Export connection token
+```
+
+## Client Skill
+
+Pair with [transcendence-memory](https://github.com/leekkk2/transcendence-memory) — an agent skill that provides built-in commands (`/tm connect`, `/tm search`, `/tm remember`, `/tm query`) for Claude Code, OpenClaw, Codex CLI, and other AI coding agents.
+
+## Documentation
+
+- [Quick Start](docs/deployment/quickstart.md)
+- [Docker Deployment](docs/deployment/docker-deployment.md)
+- [Reverse Proxy](docs/deployment/reverse-proxy.md)
+- [Environment Reference](docs/deployment/environment-reference.md)
+- [API Contract](docs/api-contract.md)
+- [Health Check](docs/operations/health-check.md)
+- [Troubleshooting](docs/operations/troubleshooting.md)
+- [Development Bootstrap](docs/development-bootstrap.md)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Pull requests welcome.
+
+## License
+
+[MIT](LICENSE)