Luna Agent

A custom minimal AI agent with persistent memory, MCP tool integration, Discord/CLI interface, and structured observability.
Runs entirely on local hardware — no cloud API costs.

~2300 lines of Python. No frameworks.

Why Custom

We evaluated existing agent frameworks and rejected them all:

• OpenClaw: 400K lines of code, 42K exposed instances on Shodan. Too large to audit, too large to trust.
• ZeroClaw: 9 days old at time of evaluation. Too immature.
• NanoClaw: Too thin — would need to rebuild most of it anyway.

The core needs (memory, tools, chat, logging) are individually well-solved problems. No 400K-line framework needed.

Architecture

Discord (discord.py)     CLI REPL (no token)
     |                        |
     v                        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, delegate, code_task
|    ├── 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               Qwen3.5-35B-A3B on 2x RTX 3090

All LLM traffic flows through a single LLMClient with a configurable endpoint URL. Today it points at localhost:8001 (llama-server). To insert an AI firewall later, change the URL to localhost:9000 — zero code changes required.

Thinking model support: Luna handles reasoning models (Qwen3.5, etc.) automatically — extracting reasoning_content, falling back to cleaned reasoning when content is empty, and stripping leaked markup (<thinking>, <tool_call>, etc.) from output.

Hardware

• Intel i7-13700K, 64GB DDR4
• 2x NVIDIA RTX 3090 (24GB each, 48GB total)
• Qwen3.5-35B-A3B Q8_0 via llama-server with layer split across both GPUs
• 131K context window, Q8_0 KV cache

Quick Start

cd ~/luna-agent
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run without Discord (interactive CLI REPL)
python -m luna

# Run with Discord
DISCORD_TOKEN=your-token-here python -m luna

Project Structure

luna-agent/
├── config.toml              # All configuration
├── mcp_servers.json         # MCP server registry
├── pyproject.toml           # Dependencies
├── luna/
│   ├── __main__.py          # Entry point (python -m luna)
│   ├── agent.py             # Core agent loop
│   ├── llm.py               # LLM client (OpenAI-compatible)
│   ├── memory.py            # Memory (SQLite + FTS5 + sqlite-vec)
│   ├── tools.py             # Native tools (bash, files, web)
│   ├── tool_output.py       # Large output persistence + filtering
│   ├── mcp_manager.py       # MCP tool client
│   ├── discord_bot.py       # Discord interface
│   ├── observe.py           # Structured JSON logging
│   └── config.py            # Config loader
├── tests/
│   ├── test_agent.py        # Agent loop tests
│   ├── test_llm.py          # LLM client tests
│   ├── test_memory.py       # Memory system tests
│   ├── test_tools.py        # Native tool tests
│   └── test_tool_output.py  # Output pipeline tests
├── luna-agent.service        # systemd unit for the agent
├── worker-agent.service      # systemd unit for llama-server (Qwen3.5-35B-A3B)
└── data/                     # Created at runtime
    ├── memory.db             # SQLite database
    ├── logs/                 # JSON log files
    │   └── luna-YYYY-MM-DD.jsonl
    └── tool_outputs/         # Persisted large tool outputs

Configuration

All settings live in config.toml. Environment variables override for secrets:

See config.toml for all available settings and their defaults.

Components

Agent (agent.py)

The orchestrator. Receives a message and session ID, then:

1. Saves the user message to memory
2. Searches for relevant memories (hybrid FTS + vector)
3. Retrieves the session summary (if any)
4. Builds a system prompt with memories, summary, and current time
5. Loads the last 20 messages for context
6. Calls the LLM with all available tools (native + MCP)
7. Enters a tool call loop (max 25 rounds):
   • Executes each tool call (native or MCP)
   • Feeds results back to the LLM
   • Repeats until the LLM responds without tool calls
8. Saves the assistant response
9. Triggers conversation summarization if enough messages have accumulated

LLM Client (llm.py)

Thin async wrapper around the OpenAI-compatible API. Single chat() method that handles tool calls, thinking model output, and per-call temperature overrides. This is the only code that talks to the LLM — the AI firewall insertion point.

Returns structured LLMResponse objects with content, reasoning, tool calls, and token usage.

Memory (memory.py)

SQLite-based persistent memory with three search strategies combined via Reciprocal Rank Fusion:

1. FTS5 keyword search — fast exact/stemmed term matching (Porter stemmer + Unicode61 tokenizer)
2. sqlite-vec cosine similarity — semantic search via nomic-embed-text-v1.5 embeddings
3. Recency + importance weighting — recent and important memories rank higher

Scoring formula:

final_score = rrf_score + (recency_weight × 2^(-age_days / 7)) + (importance / 10 × 0.1)

Database tables:

Conversation compression: Every N messages (default 50), the LLM summarizes the conversation and extracts facts with importance scores (1-10). Facts above the threshold (default 3.0) are stored as memories. This enables effectively infinite conversations — the agent always has a summary of what came before plus searchable memory of key facts.

All retrieval parameters (top_k, RRF k, recency weight, importance threshold, etc.) are in config.toml for experimentation.

Native Tools (tools.py)

Built-in tools that don't require external MCP servers:

Bash safety: Commands are checked against blocked patterns before execution:

• rm -rf /, mkfs, dd if=, shutdown, reboot, fork bombs, writes to /dev/sda
• Timeout enforcement: default 30s, max 120s
• Output capped at 50KB

Tool Output Pipeline (tool_output.py)

Handles large tool outputs so they don't overwhelm the LLM context:

1. Small outputs (< 10KB) — passed through directly
2. Large outputs — processed through a pipeline:
   • Persist — full output saved to data/tool_outputs/ with a deterministic filename (content hash + source label)
   • Python filter — keyword matching against the user's query context, with structural detection (headers, code blocks). Includes 1 line of surrounding context per match.
   • LLM extraction — if the Python filter finds fewer than 5 keyword matches, the LLM extracts relevant parts from the raw output
   • File reference — a footer with the persisted file path is appended so the agent can inspect the full output later

MCP Manager (mcp_manager.py)

Connects to community MCP servers via stdio transport. On startup it spawns configured servers, discovers their tools, and converts schemas to OpenAI function-calling format. Tool calls from the LLM are routed to the correct server automatically.

Tool namespacing: Tools are prefixed with the server name (browser__navigate, filesystem__read_file) to avoid collisions between servers.

Configure servers in mcp_servers.json:

{
  "servers": {
    "browser": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"],
      "transport": "stdio"
    }
  }
}

Adding a new tool is editing JSON — no code changes.

Discord Bot (discord_bot.py)

Responds to DMs, @mentions, and replies in threads it created. Shows a typing indicator while the agent is processing.

Session isolation: Session IDs are derived from message context to keep memory separate:

Long responses are split at newlines (preferred), spaces, or hard-split at 2000 characters to stay within Discord's limit.

Observability (observe.py)

Every LLM call, tool execution, memory operation, and Discord message is logged as structured JSON.

Dual output:

• File — data/logs/luna-YYYY-MM-DD.jsonl, one file per day, machine-parseable
• Console — human-readable format for development

What's logged:

Inspection:

# Watch logs in real-time
tail -f data/logs/luna-*.jsonl

# Search with jq
jq 'select(.event == "llm_response")' data/logs/luna-*.jsonl
jq 'select(.latency_ms > 5000)' data/logs/luna-*.jsonl

Config (config.py)

Dataclass-based configuration loaded from config.toml with environment variable overrides. Relative paths are resolved against the project root. All fields have sensible defaults — the agent starts with zero configuration if a config.toml is present.

Deployment

Copy the systemd service files and enable them:

sudo cp luna-agent.service /etc/systemd/system/
sudo cp worker-agent.service /etc/systemd/system/

sudo systemctl daemon-reload
sudo systemctl enable --now worker-agent    # Start LLM server (Qwen3.5-35B-A3B) first
sudo systemctl enable --now luna-agent      # Then the agent (depends on worker-agent)

Monitor:

journalctl -u luna-agent -f
journalctl -u worker-agent -f

CLI mode (no Discord token): The agent starts an interactive REPL where tool calls print inline as they execute, then the final response prints below. Useful for testing without Discord.

Dependencies

8 runtime packages, no heavy frameworks:

Dev: pytest, pytest-asyncio

Python: >= 3.11

What This Doesn't Include (By Design)

• No AI firewall (future — just don't block the insertion point)
• No web dashboard (future phase of observability)
• No multi-user auth (single user)
• No cloud LLM fallback (local only)
• No containers for the agent (systemd is simpler)

Contributing

See CONTRIBUTING.md for development setup, testing, and pull request guidelines.

License

MIT — Fabio Nonato, 2026