EON

A locally-running development assistant that bridges Obsidian knowledge vaults with Claude Code through the Model Context Protocol (MCP).

Features

• Eliminates repetitive context explanations to Claude Code
• Maintains project memory across sessions using Obsidian vault
• Semantic memory system learns from past decisions (ChromaDB + SQLite)
• 25 MCP tools for context retrieval, memory storage, and intelligence
• Knowledge graph connecting technologies, decisions, and concepts
• Episodic memory with session detection and extractive summarization
• Hybrid retrieval with BM25 + semantic fusion and cross-encoder reranking
• Temporal intelligence for decision timelines, evolution tracking, and trend detection
• Multi-hop reasoning with chain retrieval and what-if analysis
• Predictive intelligence with context-aware recommendations
• Cross-project intelligence for pattern discovery and knowledge transfer
• Semantic caching with cosine similarity matching for fast repeated queries
• Event-driven orchestrator for automatic file change handling
• Automatic duplicate prevention for decisions (>90% similarity detection)
• Zod-validated tool inputs for robust error handling
• Runs completely locally with zero cloud dependencies
• Compiles to single portable executable

Quick Start

# Install globally (requires Bun)
bun install -g @demgun/eon

# Interactive setup (vault path, log level, installs ~/.claude/CLAUDE.md)
eon setup

# Register with Claude Code
claude mcp add eon -s user -- bunx @demgun/eon@latest

That's it. Every Claude Code session now has 25 brain tools available.

Zero-Install Alternative

Skip the global install — just register with Claude Code directly:

claude mcp add eon -s user -- bunx @demgun/eon@latest

On first run, ~/.eon/ is auto-created with default config.

Prerequisites

• Bun >= 1.0.0
• An Obsidian vault (or any markdown folder)

CLI Commands

| Command | Description | |---------|-------------| | eon | Start MCP server (default) | | eon setup | Interactive setup wizard (run once per machine) | | eon install | Register as MCP server in Claude Code | | eon uninstall | Remove MCP server from Claude Code | | eon update | Update package and refresh CLAUDE.md to latest | | eon health | Run health checks | | eon diagnose | Run diagnostics | | eon version | Show version | | eon help | Show help |

Documentation

Comprehensive documentation is available in the docs/ directory:

| Document | Description | |----------|-------------| | API Reference | Complete HTTP API reference — 27 endpoints with request/response schemas and curl examples | | Configuration | Every config option documented with types, defaults, and environment variables | | Knowledge Packs | Pack format, built-in packs, custom pack creation, CLI commands | | Hooks & Passive Learning | Hook system architecture, passive classification, git capture, session tracking | | Code Intelligence | Tree-sitter indexing, search_code tool, supported languages, code-memory linking | | Security Hardening | Authentication, TLS proxy configs, database security, incident response | | Troubleshooting | 16 common issues with symptoms, causes, and solutions | | Production Checklist | Pre/post deployment checklists, systemd/pm2 configs, backup & recovery |

Configuration

Configuration lives in ~/.eon/.env. Created automatically by eon setup, or on first run with defaults. See docs/CONFIGURATION.md for the full reference (40+ options).

| Variable | Description | Default | |----------|-------------|---------| | VAULT_PATH | Path to your Obsidian vault | ~/.eon/vault | | LOG_LEVEL | Log level (debug/info/warn/error) | info | | NODE_ENV | Environment | production | | EON_HOME | Override home directory | ~/.eon/ | | EON_API_KEY | API key for HTTP endpoint auth | (none) | | PORT | HTTP API server port | 3333 |

Development

# Clone and install dependencies
git clone <repo-url>
cd eon
bun install

# Start dev server (uses local ./data, ./logs)
bun run dev

# Run tests
bun test

# Run tests in watch mode
bun test --watch

The dev script sets EON_HOME=. so all data stays in the project directory.

Building

# Build standalone executable for current platform
bun run build:binary

# Build for all platforms (Windows, macOS, Linux)
bun run build:all

Project Structure

eon/
├── src/
│   ├── index.ts              # Entry point (thin wrapper)
│   ├── cli/
│   │   ├── bin.ts            # CLI entry point (eon command)
│   │   ├── auto-setup.ts     # First-run home directory initialization
│   │   └── commands/         # serve, install-mcp, uninstall-mcp, update
│   ├── config/
│   │   ├── home.ts           # ~/.eon/ path resolution
│   │   ├── loader.ts         # Config loading (defaults → file → env)
│   │   └── schema.ts         # Zod config schemas
│   ├── server/               # MCP server code
│   │   └── handlers/tools/   # 25 tool handlers with Zod validation
│   ├── vault/                # Obsidian integration
│   ├── memory/               # Vector DB & embeddings
│   │   ├── chroma/           # ChromaDB integration with duplicate detection
│   │   ├── episodic/         # Session detection & episode management
│   │   └── consolidation/    # Memory importance scoring & archival
│   ├── knowledge/            # Knowledge graph & entity extraction
│   │   └── graph/            # In-memory graph with search & auto-population
│   ├── retrieval/            # Hybrid search (BM25 + semantic + reranking)
│   ├── temporal/             # Timeline construction & trend detection
│   ├── reasoning/            # Multi-hop chain retrieval & what-if analysis
│   ├── prediction/           # Decision prediction & recommendations
│   ├── cross-project/        # Cross-project pattern discovery & transfer
│   ├── optimization/         # Semantic caching & precomputation
│   ├── orchestrator/         # Event-driven coordination system
│   ├── setup/                # Interactive setup wizard
│   ├── context/              # Context assembly
│   ├── tools/                # MCP tool definitions & registry
│   └── utils/                # Shared utilities
├── assets/
│   └── CLAUDE.md             # Protocol file (shipped with npm package)
├── tests/                    # 750+ tests
└── ~/.eon/          # User data (created at runtime)
    ├── .env                  # Configuration
    ├── data/                 # SQLite + ChromaDB
    ├── logs/                 # Log files
    └── vault/                # Default vault location

Architecture Highlights

Event-Driven Orchestrator

The orchestrator automatically responds to file changes in your vault:

• Detects new decisions in decisions.md files
• Triggers automatic semantic indexing
• Coordinates between vault, memory, and context systems

Duplicate Prevention

When storing decisions, the system:

• Searches for existing decisions with >90% semantic similarity
• Returns existing ID if duplicate found (prevents bloat)
• Logs skipped duplicates for transparency

Input Validation

All tool inputs are validated using Zod schemas:

• Clear error messages for invalid parameters
• Type-safe extraction of validated inputs
• Consistent validation across all 25 tools

Embedding Cache

Uses SHA-256 hashing for cache keys to prevent collisions (improved from simple hash).

MCP Tools (25 total)

| Category | Tools | |----------|-------| | Context Retrieval | get_project_context, smart_context, recall_similar, get_code_standards, get_phase12_status | | Memory Storage | remember_decision, auto_remember, recognize_pattern, record_correction, update_progress | | Project Management | list_projects, create_project, init_project | | Knowledge Graph | search_knowledge_graph, get_episode, list_episodes | | Patterns & Corrections | get_patterns, get_corrections | | Feedback | rate_memory | | Advanced Intelligence | get_decision_timeline, analyze_decision_evolution, detect_trends, what_if_analysis, get_recommendations, find_cross_project_patterns |

Security

For production deployments, see docs/SECURITY.md. Key recommendations:

• Always set EON_API_KEY in production — generate with openssl rand -hex 32
• Server binds to localhost only by default — use a reverse proxy for remote access
• CORS is restricted to localhost — add explicit origins via corsOrigins config
• Rate limiting is enabled by default (200 req/60s)
• All file operations are protected against path traversal

API

EON exposes an HTTP API on port 3333 (default) for programmatic access. See docs/API.md for the full reference.

# Health check
curl http://localhost:3333/api/health

# Store a memory (requires API key)
curl -X POST http://localhost:3333/api/memory \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"content": "Use ESM imports", "project": "my-app", "category": "decision"}'

# Search memories
curl "http://localhost:3333/api/search?q=imports&project=my-app" \
  -H "X-API-Key: your-key"

License

MIT