🧠 Eling Agent

Personal auto-learning agent CLI — memory, skills, MCP tools, workspace, and terminal UI

"Eling" (Javanese): to remember, to be conscious, to be aware

---

✨ What is Eling Agent?

Eling Agent is a lightweight, personal auto-learning agent that runs in your terminal. It combines:

• 🧠 Local memory — stores past exchanges, learns from experience
• 📚 Skill library — auto-discovers reusable patterns from your conversations
• 📦 Workspace Manager — copy-on-write file editing with automatic project root detection
• ⏱ Live elapsed timer — real-time thinking spinner with elapsed time counter
• 🔧 MCP tools — connect any MCP server (web search, filesystem, firecrawl, etc.)
• 🎨 Rich TUI — beautiful terminal UI with banner, thinking spinner, session uptime, 10 color themes
• 🧩 Plugin system — extend with Python plugins (shell, files, web)
• ⏱ Session persistence — tracks uptime, plan steps, tool timings
• 🔍 Verbose tool output — full code/result visibility in TUI, toggleable via config
• 🧪 Auto-pytest — automatically runs pytest on touched test files after each tool round
• 🛡️ Graceful error handling — retry on timeouts/connection errors, auto-fix lint, wall-clock timeout

It uses the OpenCode Zen API for LLM inference — a free, fast API compatible with OpenAI's chat completions format.

---

🚀 Quick Start

Install

# Clone the repo
git clone https://github.com/PatrickNoFilter/eling-agent.git
cd eling-agent

# Install deps
pip install -r requirements.txt

# Configure your Zen API key
cp config.example.json config.json
# Edit config.json with your key from https://opencode.ai/zen

Run

# Interactive REPL mode
python3 agent.py

# One-shot mode
python3 agent.py "What files are in this directory?"

# Compact mode (no banner, minimal output)
python3 agent.py --compact

Setup

Get a free API key at opencode.ai/zen and set it in config.json:

Or run the interactive setup wizard:

python3 agent.py --setup

This lets you configure the provider, API key, model, agent mode, and color theme (10 palettes to choose from).

{
  "zen_api_key": "sk-zen-your-key-here",
  "zen_model": "deepseek-v4-flash-free"
}

---

🎮 Commands

Command	Description
python3 agent.py	Launch interactive REPL with TUI
python3 agent.py "query"	One-shot mode
python3 agent.py --compact	Compact mode (minimal output)
python3 agent.py --setup	Interactive setup wizard (provider, theme)
exit / quit	Exit the REPL

---

🔌 MCP Servers

Eling Agent supports any MCP server. Configure them in config.json:

{
  "mcp_servers": {
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

MCP tools are automatically loaded and presented to the model. Use mcp__ prefixed tool names in responses.

---

🧩 Plugins

Built-in plugins:

• shell — run shell commands, list directories
• files — (planned) file read/write operations

Drop a .py file with a TOOLS dict into plugins/ to add your own.

---

🧠 Memory & Skills

Eling Agent learns from every exchange:

• Memory — past Q&A pairs are stored and retrieved by relevance (BM25 + cosine similarity)
• Skills — after each response, the model decides if a reusable skill should be saved
• Persistence — database files in agent_memory.db and agent_skills.db

---

📦 Project Structure

eling-agent/
├── agent.py              # Main entry point — REPL loop, tool orchestration
├── tui.py                # Terminal UI — banner, spinner, plan panel, markdown, themes
├── provider.py           # ZenProvider — OpenAI-compatible API client
├── mcp_client.py         # MCP client — stdio-based server manager (env support)
├── memory.py             # MemoryStore — BM25 + cosine similarity retrieval, dedup
├── skills.py             # SkillLibrary — auto-learned skill storage
├── textsim.py            # Text utilities — tokenizer, similarity
├── workspace_manager.py  # Copy-on-write file editing with project detection
├── src/eling/cli.py      # Interactive setup wizard (provider, theme)
├── plugins/
│   ├── __init__.py       # Plugin loader
│   └── shell_plugin.py   # Shell command execution
├── config.example.json   # Template configuration
├── requirements.txt      # Python dependencies
├── pyproject.toml        # Package metadata (elin 0.2.0)
├── CREDITS.md            # Credits and acknowledgements
├── CREDITS.library.md    # Library-level credits
└── LICENSE               # MIT license

---

⚙️ Configuration

Key	Default	Description
zen_api_key	—	Your OpenCode Zen API key
zen_base_url	https://opencode.ai/zen/v1	API endpoint
zen_model	deepseek-v4-flash-free	Model to use
max_tool_rounds	6	Max tool call iterations per turn
max_turn_duration	300	Wall-clock timeout per turn (seconds)
verbose_tool_output	true	Show full tool args/results in TUI
memory_db	agent_memory.db	Memory database path
skills_db	agent_skills.db	Skills database path
mcp_servers	{}	MCP server configurations
theme	"cobalt"	Color theme for TUI (blue, pink, green, yellow, red, white, ocean, twilight, pastel, cobalt)

---

📚 Dependencies

Core

Package	Version	Purpose
eling	≥0.12.0	8-layer second-brain memory library (HRR, BM25, Zettelkasten)
httpx	≥0.27	HTTP client for API calls and Notion layer
requests	≥2.31	HTTP client for legacy API calls
prompt_toolkit	≥3.0	Interactive REPL prompt
rich	≥13.0	Terminal UI rendering (markdown, panels, tables)

Optional

Group	Packages	Purpose
notion	httpx	Notion integration layer
hrr	numpy≥1.24	Holographic Reduced Representations
embeddings	sentence-transformers≥3.0	Embedding-based retrieval
markdownify	markitdown[pdf]	Document-to-Markdown conversion
markdownify_all	markitdown[all]	All document formats
all	everything above	Full feature set

Install extras with:

pip install "eling-agent[hrr,embeddings,notion,markdownify]"

---

🤝 Credits

Eling Agent was created by PatrickNoFilter (@PatrickNoFilter).

Built With

Project	Contribution
OpenCode Zen	Free LLM inference API
Zero / OpenCode CLI	CLI agent patterns, telemetry format
Rich	Terminal rendering engine
Eling memory library	8-layer second brain (HRR, BM25, Zettelkasten)
Agent-Blackbox (Nous Research)	Flight recorder, 11-metric context scoring
Continuum	Multi-agent orchestration, PLOT protocol
Firecrawl MCP	Web scraping and search
Markdownify MCP (Zach Caceres)	Document conversion
Claude Code / Codex	Tool-calling loop patterns
dusterbloom	HRR phase-encoding implementation

See CREDITS.md and CREDITS.library.md for full attribution.

---

📄 License

MIT © 2026 PatrickNoFilter