MIRIX

环境要求

• 已安装 Docker 与 Docker Compose（用于启动后端与 Dashboard）
• Python 环境与 pip（用于安装 mirix-client 客户端）
• 一个可用的 LLM 服务 API Key（README 示例使用 Google AI 的 gemini-2.0-flash）
• 可访问外网以拉取镜像和安装 PyPI 包

安装与启动步骤

1. 1启动后端与面板

   在项目根目录执行该命令，会自动拉取最新镜像并后台启动后端服务与 Dashboard。

   docker compose up -d --pull always

   复制

2. 2确认服务地址

   启动后 Dashboard 在 http://localhost:5173，后端 API 在 http://localhost:8531，浏览器打开确认。

3. 3创建并设置密钥

   在 Dashboard 中创建 API key，然后将其设置为环境变量 MIRIX_API_KEY。

   export MIRIX_API_KEY=your-api-key

   复制

4. 4安装客户端

   使用 pip 安装官方 Python 客户端 mirix-client，供后续脚本调用后端。

   pip install mirix-client

   复制

5. 5初始化客户端

   在脚本中填入 api_key 与 base_url，并通过 initialize_meta_agent 配置 LLM、embedding 和各记忆智能体。

   from mirix import MirixClient
   
   client = MirixClient(
       api_key="your-api-key",
       base_url="http://localhost:8531",
   )
   
   client.initialize_meta_agent(
       config={
           "llm_config": {
               "model": "gemini-2.0-flash",
               "model_endpoint_type": "google_ai",
               "api_key": "your-api-key-here",
               "model_endpoint": "https://generativelanguage.googleapis.com",
               "context_window": 1_000_000,
           },
           "embedding_config": {
               "embedding_model": "text-embedding-004",
               "embedding_endpoint_type": "google_ai",
               "api_key": "your-api-key-here",
               "embedding_endpoint": "https://generativelanguage.googleapis.com",
               "embedding_dim": 768,
           },
           "meta_agent_config": {
               "agents": [
                   {
                       "core_memory_agent": {
                           "blocks": [
                               {"label": "human", "value": ""},
                               {"label": "persona", "value": "I am a helpful assistant."},
                           ]
                       }
                   },
                   "resource_memory_agent",
                   "semantic_memory_agent"

   复制

6. 6写入一条记忆

   调用 add 方法把对话消息写入指定用户与会话，验证记忆系统可以正常接收数据。

   client.add(
       user_id="demo-user",
       messages=[
           {"role": "user", "content": [{"type": "text", "text": "The moon now has a president."}]},
           {"role": "assistant", "content": [{"type": "text", "text": "Noted."}]},
       ],
       session_id="sess-demo-001",
   )

   复制

关键配置

如何确认成功

浏览器打开 http://localhost:5173 能看到 Dashboard，且 http://localhost:8531 后端 API 可访问，即表示后端与面板启动成功。

常见问题

注意事项

• 长时记忆数据默认存储在本地，遵循隐私优先设计，可自行控制隐私设置。
• 示例代码中的 your-api-key 与 your-api-key-here 必须替换成真实密钥后才能运行。
• 需要先完成 Docker 启动并创建 API key，再执行客户端初始化脚本。
• 更多用法见官方文档 https://docs.mirix.io 与官网 https://mirix.io。