Elen
Learning Nodes for Agents
Elen is an open-source MCP server that records the decisions your coding agent makes, with the limits that bound them, and marks old decisions as superseded. It installs with one npx line, works with Cursor, Claude Code and any MCP client, and keeps decisions in a local SQLite file.
Join Discord · ClawHub Skill · See how it works · Spec · Roadmap · Contributing · License
--- ## 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 ```typescript 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. ```json { "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. ```json { "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](#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](./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](https://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: ```json { "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`](../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) ```markdown # 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](../AGENTS.md) 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: ```json { "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](./CONTRIBUTING.md). All contributions require a signed CLA. ## License [AGPL-3.0](./LICENSE) — see [open core model](./SPEC.md#license) for details. Built by [Learning Nodes](https://www.learningnodes.com).