Elen

---

The Problem

Agents burn massive amounts of context window tokens re-litigating the same architectural decisions, searching for the same constraints, and writing the same rationale. Chat logs are ephemeral. Standard vector DBs flood the context window with fuzzy, irrelevant text.

What Elen Does

Elen gives agents a Token-Efficient Decision Memory Protocol. It allows agents to build a permanent, immutable graph of decisions (the "Elen Decision Network") without destroying their context limits.

Instead of stuffing the prompt with past chats, Elen forces a pointer-first retrieval model:

1. SUGGEST — Retrieve only minimal Top-K pointer IDs (dec:ENG-1a2b).
2. EXPAND — Only fetch the full text if the pointer is explicitly requested.
3. COMMIT — Write decisions using hashed constraint sets to avoid duplication.
4. SUPERSEDE — Explicitly deprecate outdated decisions to advance the graph.

"Agents don't get smarter with bigger models. They get smarter with better reasoning processes. Elen is that process."

Quick Start

import { Elen } from '@learningnodes/elen';

const elen = new Elen({
  agentId: 'frontend-agent',
  projectId: 'my-project', // auto-detected from git remote if omitted
  storage: 'sqlite',
});

// 1. Suggest (Pointer-First Retrieval)
const pointers = await elen.suggest('checkout latency constraints');
// Returns: [{ id: 'dec:MKT-9f21', summary: 'Mobile checkout rendering SLAs' }]

// 2. Expand (On-Demand Materialization)
const record = await elen.expand('dec:MKT-9f21');
// Resolves full constraints: "All checkout flows must render under 1.5s"

// 3. Commit (Graph Wiring)
const newDecision = await elen.commit({
  question: 'Which payment element to use?',
  domain: 'frontend',
  decisionText: 'Stripe Elements (native rendering over redirect)',
  constraints: ['must render < 1.5s', 'PCI compliant'],
  refs: ['dec:MKT-9f21'] // Explicitly linking to Marketing's constraint
});

console.log(newDecision.decision_id); // dec:FRN-a1b2c3 - Frozen, queryable

Via MCP (zero-code integration)

Add Elen as an MCP server — your agent gets tools with descriptions that tell it when to use them. No SDK required.

{
  "mcpServers": {
    "elen": {
      "command": "npx",
      "args": ["-y", "@learningnodes/elen-mcp@0.3.1"]
    }
  }
}

Project identity (DS-0.5)

project_id is resolved in this order — never from your OS username:

1. --project flag or "project" in ~/.elen/config.json
2. Optional venture_map in config (folder segment → project, e.g. learningnodes across many repos)
3. Normalized git remote get-url origin → owner/repo
4. Git repo root directory name

If resolution fails, MCP/CLI exits with guidance instead of writing to a wrong namespace.

{
  "project": "my-app",
  "venture_map": {
    "learningnodes": ["marketplace-repos", "elen"]
  }
}

Observability & CLI

Tool / command	Purpose
elen_get_context	Threads plus meta (agent, project, db path, counts, other projects)
elen_status / elen status	Same meta snapshot
elen_consolidate / elen consolidate	Suggest duplicate/stale clusters (--apply runs thread enricher after backup)
elen project rename|merge	Re-tag project_id (+ search_log)
elen prune	Drop blank records (--project optional)
elen backup	WAL checkpoint + copy (auto before destructive ops)
elen export / elen import	JSON portability
elen stats	Per-project/agent counts + duplicate candidates

Startup stderr logs: agent, project, db, record counts. Native SQLite uses WAL + busy_timeout=5000 for safe multi-client access. If the native module ABI mismatches your Node version, you get an actionable message — run npx @learningnodes/elen-mcp@latest so each client gets a matching prebuild.

[!IMPORTANT] MCP alone is not enough. Agents won't reliably call elen_suggest or elen_commit without behavioral priming. Add an AGENTS.md file to your repo root — see Making Agents Log Decisions below.

How It Works

Agent faces a problem
    │
    ├── SUGGEST: "What are the relevant minimal pointers?"
    │   → Finds [dec:ENG-1a, dec:ENG-2b]
    │
    ├── EXPAND: "dec:ENG-2b looks relevant, fetch the full payload."
    │   → Retrieves constraints and full rationale into context window
    │
    └── COMMIT / SUPERSEDE: "I've solved it."
        → Writes a new explicit node to the graph

Key Concepts

Concept	What
Top-K Pointers	Agents retrieve IDs and summaries first, saving tokens.
Constraint Sets	Reusable, SHA-256 hashed plain-text rules ("budget < 500ms").
Explicit DAG	Decisions explicitly reference (refs) or override (supersedes) others.
Project Segmentation	Decisions scoped per project with strict isolation by default (open core). Cross-workspace / shared-pool discovery is proprietary — see elen-cloud/ai-service PostgresStorage, not shipped in @learningnodes/elen*.

What's Built

Feature	Status
TypeScript Base SDK (suggest, expand, commit, supersede)	✅ Shipped
MCP server with standard protocol tools	✅ Shipped
Local SQLite storage (~/.elen/decisions.db)	✅ Shipped
Constraint Set hashing & Deduplication	✅ Shipped
Explicit Graph DAG (refs & supersedes wiring)	✅ Shipped
Project segmentation (git remote / venture map / explicit; never OS username)	✅ DS-0.5
Local graph observability (meta, elen_status, startup counts)	✅ DS-0.5
Commit-time duplicate suggestions + elen consolidate	✅ DS-0.5
Admin CLI (rename, merge, prune, backup, export, import, stats)	✅ DS-0.5
Cross-workspace / shared-pool prior discovery	❌ Not open — proprietary elen-cloud (PostgresStorage)
Elen Workstation (cloud dashboard + local data)	✅ Shipped
Bundled Local API (opt-in via ELEN_LOCAL_API=true)	✅ Shipped

See ROADMAP.md for what's next.

Elen local dashboard

Elen is the open-source part of Learning Nodes, the DecisionOps workspace. For the business decisions behind the code: https://workstation.learningnodes.com?utm_source=elen-readme&utm_medium=referral&utm_campaign=github-readme

The Elen Workstation is a visual dashboard for your decision network at app.elen.learningnodes.com. Your data never leaves your machine — the cloud serves only the UI shell, and the browser fetches data from your local MCP.

To enable the workstation, add ELEN_LOCAL_API to your MCP config:

{
  "mcpServers": {
    "elen": {
      "command": "npx",
      "args": ["-y", "@learningnodes/elen-mcp@0.3.1"],
      "env": {
        "ELEN_LOCAL_API": "true"
      }
    }
  }
}

Open your IDE → MCP starts → local API starts on port 3333 → workstation auto-connects. No manual steps.

Making Agents Log Decisions

Agents have access to the protocol verbs but won't intuitively use them without explicit trigger conditions. The tool description tells the agent what the tool does — but agents are task-focused and don't self-assess "should I search precedent right now?" mid-conversation.

The fix: Include instructions to use the Elen MCP in your prompt or add an AGENTS.md file to your repo root. This file is automatically loaded into the agent's context at the start of every session across Antigravity, Claude Code, Cursor, and Copilot. It tells the agent:

• When to query: Before formulating any technical plan or making an implementation choice.
• When to commit: After successfully resolving errors, selecting technologies, or making architectural trade-offs.
• How to format: Extracting constraints as discrete rules, pointing explicitly to prior IDs if available.

Protocol Instructions (Copy to .cursorrules or System Prompt)

# Epistemic Decision Memory Protocol

You must adhere to the Minimal Token Protocol for decisions:

1. Pointer-First Retrieval: Before making a technical decision, ALWAYS use elen_suggest to retrieve Top-K minimal pointers.
2. On-Demand Expansion: If a pointer looks relevant, you MUST call elen_expand on that specific ID. Do not hallucinate constraints.
3. Commiting Atoms: When deciding, use elen_commit. Summarize constraints into plain-text arrays (e.g. "budget < 500ms").
4. Graph Revision: If a decision invalidates a precedent, you MUST use elen_supersede to advance the graph state.

See the AGENTS.md template in the repo root for the complete behavioral wrapper.

Without AGENTS.md, the agent has the tool but no habit. With it, decision logging becomes a session norm — like running tests before committing.

IDE Compatibility

Elen works with any IDE or agent that supports MCP (Model Context Protocol) — the open standard for AI tool integration.

IDE / Agent	Works Today
Claude Code (Anthropic)	✅
Cursor	✅
Windsurf (Codeium)	✅
VS Code + Copilot	✅
Custom agents (LangChain, CrewAI, etc.)	✅ via SDK

Same config for all:

{
  "mcpServers": {
    "elen": {
      "command": "npx",
      "args": ["-y", "@learningnodes/elen-mcp@0.3.1"]
    }
  }
}

All decisions are stored locally in ~/.elen/decisions.db by default. Nothing leaves your machine unless you opt into proprietary cloud sync (elen-cloud).

Open-core boundary

Open (AGPL)	Proprietary (elen-cloud)
MCP + 4 verbs, @learningnodes/elen*, local SQLite	ai-service (Elen Lattice LLM routes), PostgresStorage, operator panel, billing
Principal/project-scoped isolation by default	Cross-workspace prior-decision pool (interim; sharing panel planned)
Strict per-project Suggest / Expand	Workstation gateway proxy + workspace_billing

Learning Nodes Workstation uses the proprietary stack for live AI; the npm packages remain the portable open-core surface.

Project Structure

Elen/
├── packages/
│   ├── core/           # Types, schemas, validation logic
│   ├── sdk-ts/         # TypeScript SDK (@learningnodes/elen)
│   ├── mcp-server/     # MCP server + bundled local API (@learningnodes/elen-mcp)
│   └── local-api/      # Standalone local API (for debugging)
├── SPEC.md             # Protocol specification
├── WHITE_PAPER.md      # Design principles & vision
└── ROADMAP.md          # Product roadmap

Contributing

See CONTRIBUTING.md. All contributions require a signed CLA.

License

AGPL-3.0 — see open core model for details.

Built by Learning Nodes.