Helixir

Helixir

An elder brain for LLM agents: memory that never forgets, reasons in chains, and sees connections others can't.

⚡ Quick Start · What is Helixir? · Contents

---

Contents

• [What is Helixir?](#what-is-helixir)
• [Philosophy](#philosophy)
• [Quick Start](#quick-start)
• [One-command install](#one-command-install)
• [Prerequisites](#prerequisites)
• [How It Works](#how-it-works)
• [Read path (zero LLM calls)](#read-path-zero-llm-calls)
• [Architecture](#architecture)
• [Ontology](#ontology)
• [Graph Schema](#graph-schema)
• [MCP Tools](#mcp-tools)
• [Integration](#integration) — Cursor, Claude Desktop
• [Configuration](#configuration)
• [Development](#development)
• [Upgrading](UPGRADING.md) — v0.3.x → v0.4.0 migration

---

What is Helixir?

Helixir gives AI agents memory that persists between sessions — and more than that: memory that reasons. When an agent starts a new conversation, it recalls past decisions, preferences, goals and the chains of reasoning behind them, not a flat log of similar text.

Every input is LLM-extracted into atomic facts, classified by ontology (8 types), linked to entities and to other facts by typed logical edges (BECAUSE, IMPLIES, CONTRADICTS, SUPPORTS), and stored in one graph+vector engine. Retrieval is a hybrid of dense vectors, BM25 keyword search and graph traversal ranked by Personalized PageRank — with zero LLM calls on the read path, so it is exactly as fast on a local ollama model as on a cloud API.

Built on HelixDB (graph + vector database) with native MCP support for Cursor, Claude Desktop, Claude Code and any MCP-compatible client.

| Plain RAG memory | Helixir | |:-----------------|:--------| | Returns similar text chunks | Returns facts with provenance: what matched directly, what was pulled through which edge, and why | | Append-only — grows forever | Curated writes: ADD / UPDATE / SUPERSEDE / NOOP decided per fact | | No reasoning trail | Causal chains: A because B, A implies C — and connect_memories(A, B) finds the path between any two concepts | | LLM in the retrieval loop | Read path is LLM-free: ~15–30 ms warm searches, fully local | | Single-user silo | Shared graph: one fact, many knowers, consensus ranking, conflict detection | | Silent overwrites | Memory charter: conflicting writes escalate to the agent as questions |

Philosophy

Three principles drive every design decision; the long version lives in [helixir/doc/design-rationale.md](helixir/doc/design-rationale.md).

An elder brain forgets nothing. There is deliberately no delete tool. Outdated facts are superseded — the old version stays in history (HAS_HISTORY edges, valid_until), reachable forever. Why? Because the value of memory is not in single facts but in long chains between them: Rajasthan weather → guar harvest → guar gum price → fracking costs → shale stocks. A memory that prunes "irrelevant" facts destroys the middle of chains it cannot yet see. Time affects attention (what surfaces first), never reachability (what can be found through connections).

The writer pays, the reader flies. All expensive work — extraction, dedup decisions, relation inference — happens at write time. Reading is pure math over precomputed structure: no LLM, no re-embedding when warm. This is what makes a fully local setup (ollama + HelixDB) practical.

The memory does not gaslight its owner. Writes that conflict with what is already known — a reversed preference, a contradiction, anything destructive — are not resolved silently. They come back in add_memory.needs_clarification as ready-to-ask questions, governed by a human-editable [memory charter](helixir/memory-charter.md): a constitution of rules the engine may never override.

---

Quick Start

One-command install

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

The script will:

1. Check prerequisites (Rust, Docker)
2. Clone the repo and build from source
3. Start HelixDB via Docker
4. Deploy the graph schema
5. Generate MCP config for your IDE

Or install manually:

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

Prerequisites

• Rust 1.85+ — rustup.rs
• Docker — for HelixDB (install)
• API key — at least one LLM provider:
• Cerebras (free tier, ~3000 tok/s)
• OpenAI
• Ollama (local, no key needed)

---

How It Works

           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
                      |
                Memory charter check ── conflicts? ──> needs_clarification
                      |                                (agent asks the human)
                Store in HelixDB (graph + vector)

Architecture

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)

Read path (zero LLM calls)

Query ──> embedding (cached) ──┬──> dense ANN (HelixDB HNSW)   ──┐
                               └──> BM25 keyword (SearchBM25)  ──┤
                                                                 ├──> RRF fusion
                                                                 v
                              graph expansion: one batched HQL call per depth level
                              (8 edge families, parent provenance kept)
                                                                 v
                              Personalized PageRank over the typed ego-network
                              final rank = 0.3·cosine + 0.5·PPR + 0.2·freshness
                                                                 v
                    results with provenance: origin=seed|graph, edge, parent, ppr

Warm search: p50 ≈ 15–30 ms. Reasoning chains and connect_memories run on the same machinery — the read path works identically with no LLM configured at all.

---

Ontology

Every memory is classified into one of 8 concept types. The LLM extractor assigns the type during ingestion; search_by_concept retrieves memories by type.

| Type | What it captures | Example | |:-----|:-----------------|:--------| | fact | Objective knowledge, statements about the world | "Rust compiles to native code" | | preference | Likes, dislikes, tastes, favorites | "I prefer dark mode in all editors" | | skill | Abilities, competencies, expertise | "I can write fluent Python" | | goal | Plans, aspirations, objectives | "I want to learn Japanese this year" | | opinion | Subjective beliefs, judgments, viewpoints | "I think remote work is more productive" | | experience | Past events, situations lived through | "I lived in Berlin for 3 years" | | achievement | Accomplished milestones, completed goals | "I built a working compiler from scratch" | | action | Specific tasks performed, operations executed | "I deployed the CI/CD pipeline yesterday" |

Ontology hierarchy

The concept types are organized into a tree stored in HelixDB:

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

The hierarchy enables traversal: searching for "Attribute" returns all facts, preferences, skills, goals, and opinions. Entity types (Person, Organization, etc.) are used for extracted named entities.

---

Graph Schema

Helixir stores everything as a typed graph: 15 node types connected by 33 edge types.

Node types

| Node | Purpose | Key fields | |:-----|:--------|:-----------| | Memory | Core unit — one atomic fact | content, memorytype, certainty, importance, userid | | User | Owner of memories | userid, name | | Entity | Named thing extracted from text | name, entitytype, aliases | | Concept | Ontology node (Fact, Skill, Goal...) | name, level, parentid | | Context | Situational scope (work, personal...) | name, contexttype | | Session | Conversation session | sessionid, status | | Agent | AI agent that created a memory | agentid, role, capabilities | | HistoryEvent | Audit log entry for a memory | action, oldvalue, newvalue, timestamp | | MemoryChunk | Fragment of a long memory | content, position, tokencount | | Reasoning | Reasoning node | reasoningtype, confidence | | Constraint | Rule applied in a context | rule, constrainttype, priority | | MemoryEmbedding | Vector embedding (search index) | content, createdat | | EntityEmbedding | Vector embedding for entity search | name | | DocPage / DocChunk / CodeExample / ErrorCode | Documentation pipeline (reserved) | — |

Edge types (active)

These 24 edge types are used in the current pipeline:

| Edge | From → To | What it means | |:-----|:----------|:--------------| | HASMEMORY | User → Memory | User owns this memory | | INSTANCEOF | Memory → Concept | Memory is of this ontology type | | BELONGSTOCATEGORY | Memory → Concept | Memory belongs to this category | | MENTIONS | Memory → Entity | Memory mentions this entity | | EXTRACTEDENTITY | Memory → Entity | Entity was LLM-extracted from this memory | | RELATESTO | Entity → Entity | Two entities are related (typed: worksat, uses, etc.) | | VALIDIN | Memory → Context | Memory applies in this context (work, personal...) | | OCCURREDIN | Memory → Context | Memory is about an event in this context | | AGENTCREATED | Agent → Memory | This agent created the memory | | HASHISTORY | Memory → HistoryEvent | Audit trail: who changed what and when | | HASCHUNK | Memory → MemoryChunk | Memory split into chunks (long texts) | | NEXTCHUNK | MemoryChunk → MemoryChunk | Sequential chunk ordering | | CHUNKHASEMBEDDING | MemoryChunk → MemoryEmbedding | Chunk's vector index | | MEMORYRELATION | Memory → Memory | General relation between memories (typed) | | IMPLIES | Memory → Memory | A logically leads to B | | BECAUSE | Memory → Memory | A is the reason for B | | CONTRADICTS | Memory → Memory | A conflicts with B | | SUPERSEDES | Memory → Memory | A replaces outdated B | | HASEMBEDDING | Memory → MemoryEmbedding | Memory's vector index for semantic search | | ENTITYHASEMBEDDING | Entity → EntityEmbedding | Entity's vector index | | HASSUBTYPE | Concept → Concept | Ontology hierarchy (Attribute → Skill) | | PAGETOCHUNK | DocPage → DocChunk | Documentation structure | | CHUNKTOEMBEDDING | DocChunk → ChunkEmbedding | Documentation vector index | | SUPPORTS | Memory → Memory | A provides evidence for B |

Edge types (reserved)

These 9 edge types are defined in the schema with HQL queries ready, but not yet called from the Rust pipeline. They are infrastructure for planned features:

| Edge | From → To | Planned use | |:-----|:----------|:------------| | INSESSION | User → Session | Session tracking | | CREATEDIN | Memory → Session | Which session created this memory | | ISA | Concept → Concept | Dynamic ontology extension | | CONCEPTRELATEDTO | Concept → Concept | Cross-concept links | | PARTOF | Entity → Entity | Hierarchical entity relations | | APPLIESIN | Constraint → Context | Constraint scoping | | CHUNKMENTIONSCONCEPT | DocChunk → Concept | Documentation ↔ ontology links | | CONCEPTHASEXAMPLE | Concept → CodeExample | Code examples per concept | | ERRORREFERENCES_CONCEPT | ErrorCode → Concept | Error catalog |

---

MCP Tools

Memory

| Tool | What it does | |:-----|:-------------| | add_memory | Extract atomic facts, deduplicate, store with entities and relations. Charter conflicts come back in needs_clarification | | search_memory | Hybrid search (vector + BM25 + graph, PPR-ranked) with temporal modes: recent (4h), contextual (30d), deep (90d), full. Every result carries provenance (origin, edge, parent, ppr) | | connect_memories | "How is A related to B?" — bidirectional path discovery between two concepts, with edge types and cumulative confidence | | search_by_concept | Filter by ontology type: skill, preference, goal, fact, opinion, experience, achievement, action | | search_reasoning_chain | Traverse causal/logical connections: IMPLIES, BECAUSE, CONTRADICTS, SUPPORTS — LLM-free | | get_memory_graph | Return memory as a graph of nodes and edges | | update_memory | Modify existing memory content | | search_incomplete_thoughts | Find auto-saved incomplete FastThink sessions |

FastThink (working memory)

Isolated scratchpad for complex reasoning. Nothing pollutes long-term memory until you explicitly commit.

| Tool | What it does | |:-----|:-------------| | think_start | Open a new thinking session | | think_add | Add a reasoning step (types: reasoning, hypothesis, observation, question) | | think_recall | Pull facts from long-term memory into the session (read-only) | | think_conclude | Mark a conclusion | | think_commit | Save the conclusion to long-term memory | | think_discard | Discard the session without saving | | think_status | Check session state: thought count, depth, elapsed time |

Flow: think_start → think_add (repeat) → think_recall (optional) → think_conclude → think_commit

If a session times out, partial thoughts are auto-saved with an [INCOMPLETE] tag and recoverable via search_incomplete_thoughts.

---

Integration

Cursor

Add to ~/.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",
        "HELI

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nikita-rulenko](https://github.com/nikita-rulenko)
- **Source:** [nikita-rulenko/Helixir](https://github.com/nikita-rulenko/Helixir)
- **License:** MIT

Install and usage instructions live in the source repository linked above.