Luna Agent

Persistent Memory

SQLite + FTS5 + sqlite-vec hybrid search. Keyword, semantic, and recency-weighted retrieval with automatic conversation summarization.

MCP Tools

Connect any MCP-compatible tool server via JSON config. Built-in tools for bash, files, web fetch, and web search.

Discord Interface

DMs, mentions, and threaded conversations with session isolation. Typing indicators and smart message splitting.

Local-First

Runs on your hardware with any OpenAI-compatible endpoint. No cloud API costs. Tested with llama-server + Qwen3-Coder-Next.

Structured Observability

Every LLM call, tool execution, and memory operation logged as structured JSON. One JSONL file per day.

No Frameworks

~2300 lines of Python. 8 runtime dependencies. Every line is auditable. No 400K-line agent framework needed.

Architecture

Discord (discord.py)
     |
     v
+-----------------------+
|    Luna Agent Core    |
|                       |
|  agent.py             |  agent loop: msg -> memory -> prompt -> LLM -> tools -> respond
|    +-- llm.py         |  single LLM client, configurable endpoint
|    +-- memory.py      |  SQLite + FTS5 + sqlite-vec hybrid search
|    +-- tools.py       |  native tools: bash, files, web fetch, web search
|    +-- tool_output.py |  smart output pipeline for large results
|    +-- mcp_manager.py |  MCP client for community tool servers
|    +-- observe.py     |  structured JSON logging
|                       |
+-----------------------+
         |
         v
   llama-server          any OpenAI-compatible endpoint

Quick Start


# Clone and install
git clone https://github.com/nonatofabio/luna-agent.git
cd luna-agent
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Configure MCP servers (optional)
cp mcp_servers.example.json mcp_servers.json

# Run tests
pytest tests/ -v

# Run the agent
python -m luna