Helixir Rs

Helixir

Graph-based persistent memory for LLM agents.

Associative recall, causal reasoning, ontology classification — out of the box.

Quick Start · How It Works · Ontology · Graph Schema · MCP Tools · Configuration

______________________________________________________________________

什么是Helixir？

Helixir为AI代理提供支持 会话之间持续存在的内存当由Helixir驱动的代理开始新的对话时，它会回忆起过去的决定、偏好、目标和推理链——不是从一个平面日志中，而是从一个 相互关联事实图.

每条信息都被LLM提取为原子事实，按本体（8种类型）分类，链接到命名实体，并与向量嵌入一起存储以进行语义搜索。重复检测、矛盾跟踪和替换会自动发生。

______________________________________________________________________

快速开始

一个命令安装

curl -fsSL https://raw.githubusercontent.com/nikita-rulenko/Helixir/main/install.sh | bash

脚本将：

1. 检查先决条件（Rust、Docker）
2. 克隆仓库并从源代码构建
3. 通过Docker启动HelixDB
4. 部署图形架构
5. 为IDE生成MCP配置

或手动安装：

git clone https://github.com/nikita-rulenko/Helixir.git
cd helixir

make build          # Build release binary
make setup          # Start HelixDB + deploy schema
make config         # Print MCP config to paste into your IDE

先决条件

• 锈蚀1.83+ — rustup.rs
• 码头工人 --HelixDB(安装)
• API密钥 --至少一个LLM提供者：

- 赛博拉斯 （免费等级，约3000 tok/s） - 开放人工智能 - 奥拉玛 （本地，无需密钥）

______________________________________________________________________

运作原理

           Input: "I deployed the server to AWS and prefer using Terraform"
                                      |
                                LLM Extraction
                                      |
                      +---------------+---------------+
                      |                               |
              Memory: "I deployed         Memory: "I prefer
              the server to AWS"          using Terraform"
              type: action                type: preference
                      |                               |
                +-----+-----+                   +-----+-----+
                |           |                   |           |
            Entity:     Entity:            Entity:      Concept:
            "AWS"       "server"           "Terraform"  Preference
                      |
                Phase 1: Personal search (dedup check)
                Phase 2: Cross-user search (shared facts)
                      |
                Decision: ADD / UPDATE / SUPERSEDE / NOOP
                      |
                Store in HelixDB (graph + vector)

建筑

MCP Server (stdio)                        IDE (Cursor / Claude Desktop)
       |                                           |
  HelixirClient                               MCP Protocol
       |
  ToolingManager ──── FastThinkManager
       |                    |
  +----+----+----+     petgraph (in-memory)
  |    |    |    |          |
Extract Decision Entity  commit to DB
  |    Engine  Manager       |
Search    |    Ontology      |
Engine  Reasoning Manager    |
  |    Engine    |           |
  +----+----+----+-----------+
       |
  HelixDB Client (HTTP)
       |
  HelixDB (graph + vector database)

请参阅中的完整架构图 helixir/diagrams/.

______________________________________________________________________

本体论

每个记忆都被分类为 8种概念类型LLM提取器在摄入期间分配类型； search_by_concept 按类型检索记忆。

本体层次结构

概念类型被组织成存储在HelixDB中的树：

Thing
  ├── Attribute
  │     ├── Fact
  │     ├── Preference
  │     ├── Skill
  │     ├── Goal
  │     ├── Opinion
  │     └── Trait
  ├── Event
  │     ├── Action
  │     ├── Experience
  │     └── Achievement
  ├── Entity
  │     ├── Person
  │     ├── Organization
  │     ├── Location
  │     ├── Object
  │     └── Technology
  ├── Relation
  └── State

层次结构允许遍历：搜索“属性”会返回所有事实、偏好、技能、目标和意见。实体类型（个人、组织等）用于提取命名实体。

______________________________________________________________________

图形架构

Helixir将所有内容存储为类型化图形： 15种节点类型 由...连接 33种边缘类型.

节点类型

边缘类型（活动）

这24种边缘类型用于当前管道：

边缘类型（保留）

这9种边缘类型在HQL查询就绪的模式中定义，但尚未从Rust管道调用。它们是计划功能的基础设施：

______________________________________________________________________

MCP工具

记忆

FastThink（工作记忆）

用于复杂推理的独立草稿。在你明确承诺之前，没有什么会污染长期记忆。

流量： think_start → think_add （重复）→ think_recall （可选）→ think_conclude → think_commit

如果会话超时，部分想法将自动保存 [INCOMPLETE] 标记并可通过以下方式恢复 search_incomplete_thoughts.

______________________________________________________________________

整合

光标

添加 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "helixir": {
      "command": "/path/to/helixir-mcp",
      "env": {
        "HELIX_HOST": "localhost",
        "HELIX_PORT": "6969",
        "HELIX_LLM_PROVIDER": "cerebras",
        "HELIX_LLM_MODEL": "gpt-oss-120b",
        "HELIX_LLM_API_KEY": "YOUR_KEY",
        "HELIX_EMBEDDING_PROVIDER": "openai",
        "HELIX_EMBEDDING_MODEL": "nomic-embed-text-v1.5",
        "HELIX_EMBEDDING_URL": "https://openrouter.ai/api/v1",
        "HELIX_EMBEDDING_API_KEY": "YOUR_KEY"
      }
    }
  }
}

克劳德桌面版

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

与上述JSON结构相同。

光标规则（推荐）

添加 光标设置>规则 所以代理实际上使用了它的内存：

# Core Memory Behavior
- At conversation start, call search_memory to recall relevant context
- After completing tasks, save key outcomes with add_memory
- Use search_by_concept for skill/preference/goal queries
- Use search_reasoning_chain for "why" questions

# FastThink for Complex Reasoning
- Before major decisions, use FastThink to structure your reasoning
- Flow: think_start -> think_add (repeat) -> think_recall -> think_conclude -> think_commit

# What to Save
- ALWAYS save: decisions, outcomes, architecture changes, error fixes, preferences
- NEVER save: grep results, lint output, file contents, temporary data

______________________________________________________________________

配置

所有设置都作为环境变量传递。

必需

可选的

提供商预设

Cerebras + OpenRouter (recommended — fast inference, cheap embeddings)

HELIX_LLM_PROVIDER=cerebras
HELIX_LLM_MODEL=gpt-oss-120b
HELIX_LLM_API_KEY=csk-xxx           # https://cloud.cerebras.ai

HELIX_EMBEDDING_PROVIDER=openai
HELIX_EMBEDDING_URL=https://openrouter.ai/api/v1
HELIX_EMBEDDING_MODEL=nomic-embed-text-v1.5
HELIX_EMBEDDING_API_KEY=sk-or-xxx   # https://openrouter.ai/keys

Fully local with Ollama (no API keys, fully private)

# Install Ollama: https://ollama.com
ollama pull llama3:8b
ollama pull nomic-embed-text

HELIX_LLM_PROVIDER=ollama
HELIX_LLM_MODEL=llama3:8b
HELIX_LLM_BASE_URL=http://localhost:11434

HELIX_EMBEDDING_PROVIDER=ollama
HELIX_EMBEDDING_URL=http://localhost:11434
HELIX_EMBEDDING_MODEL=nomic-embed-text

OpenAI only (simple, one API key)

HELIX_LLM_PROVIDER=openai
HELIX_LLM_MODEL=gpt-4o-mini
HELIX_LLM_API_KEY=sk-xxx

HELIX_EMBEDDING_PROVIDER=openai
HELIX_EMBEDDING_MODEL=text-embedding-3-small
HELIX_EMBEDDING_API_KEY=sk-xxx

______________________________________________________________________

发展

make build          # Build release binary
make test           # Run all tests
make check          # cargo check + clippy
make run            # Run MCP server locally (debug)
make deploy-schema  # Deploy schema to running HelixDB
make docker-up      # Start HelixDB container
make docker-down    # Stop HelixDB container
make test-e2e-hive  # Hive cross-user E2E (HelixDB + LLM + embeddings; set HELIX_* like MCP)

蜂巢E2E： make test-e2e-hive 跑 hive_cross_user_collective_link_e2e （默认情况下忽略 cargo test).它为两个人增加了同样的事实 user_id 重视和主张集体 user_count ≥ 2 第一个记忆。LLM决策可能不稳定——必要时重试。

项目结构

helixir-rs/
  helixir/
    src/
      bin/
        helixir_mcp.rs          # MCP server entry point
        helixir_deploy.rs       # Schema deployment CLI
      core/                     # Config, client, search modes
      db/                       # HelixDB client
      llm/                      # LLM providers, extractor, decision engine
      mcp/                      # MCP server, params, cognitive protocol
      toolkit/
        tooling_manager/        # Main pipeline (add, search, CRUD, events)
        mind_toolbox/           # Search engine, entity, ontology, reasoning
        fast_think/             # Working memory (petgraph-based)
    schema/
      schema.hx                 # Node/edge definitions (15 nodes, 33 edges)
      queries.hx                # HQL queries (100+)
    diagrams/                   # Architecture diagrams (D2 + PNG)
    Dockerfile
    docker-compose.yml

______________________________________________________________________

许可证

麻省理工学院 ©2025-2026尼基塔·鲁连科

链接

• 螺旋分贝 --图形+矢量数据库
• MCP规范 --模型上下文协议
• 赛博拉斯 --快速LLM推理（自由层）
• 开放路由 -统一LLM/嵌入API