ExecAI

SOVEREIGN · MEMORY-DRIVEN AI AGENT — v4.0 · PYTHON · MIT

“Memory is not a history log: it is the ability to learn.” A modular agentic framework that runs on your own local models or in the cloud, with a real long-term memory. The whole pipeline is yours — the model, the tools, the memory, the rules. 100% offline-capable on modest hardware.

> Highlights

  • Four backends, one API — Ollama, llama.cpp, DashScope (Qwen) and DeepSeek: streaming, tool calls, vision and thinking handled per backend according to the official conventions. Switch cloud ↔ local without changing a line of code.
  • Hybrid RAG memory — ChromaDB + BM25 + temporal decay, local embeddings. The agent learns from every session: automatic distillation of durable facts with deduplication and merging — no duplicates, ever.
  • Memory resilience — embedder down? Falls back to lexical mode. Slow server? Proportional compression budget with an anti-truncation guard: no silent loss of facts.
  • Hardened file tools — exact-string or line-range edits, atomic writes (mode/uid/gid preserved), expected_sha256 against concurrent edits, binary detection, CRLF smoothing, built-in grep/glob.
  • Context overflow protection — per-backend budget (32k local → 128k cloud), LLM-summary compaction of old turns, tool-result truncation, loop detection.
  • Graduated safety — plan (read-only) / edit (confirmation for sensitive actions) / auto modes, blocked patterns, and a PARANOID dry-run.
  • Persistent sessions — conversation resume, markdown skills (skill_use), project rules auto-loaded (system.md, AGENTS.md).

> The RAG Memory — the Heart of ExecAI

Conversation ──► LLM distillation ──► durable facts (FR, <200 chars)
                     │                    │
                     │                    ├─ search: hybrid cosine + BM25 + time
                     │                    ├─ deduplication: merge when similarity ≥ 0.85
                     │                    └─ storage: ChromaDB (local embeddings, port 8081)
                     │
                     └─ at session end (chat exit, one-shot with --session)

Relevant temporal search filters off-topic cards; every session distils what is worth remembering. The result: an assistant that accumulates real knowledge, not just history.

> Quick Start

git clone https://git.nunki.org/nunki/execai.git
cd execai
python -m venv .venv
./.venv/bin/pip install -e ".[all,dev]"
cp .env.example .env          # add API keys only if using cloud backends

./execai.sh llama             # chat with a local llama.cpp model
./execai.sh deepseek          # chat with deepseek-flash (key in .env)
./execai.sh ollama            # chat with ollama
python -m execai --mode plan "..."   # read-only: nothing gets written
python -m execai --safe "rm -rf /tmp/x"   # STRICT safety level

Local servers in one script (launch_llama.sh): LLM on port 8080, memory embedder on port 8081. Systemd units included for the embedder, the web console and the memory editor — all bound to 127.0.0.1, reachable through an SSH tunnel.

> Source & Documentation

Full test-bench · Python 3.10+ · MIT license · backends: Ollama · llama.cpp · Qwen · DeepSeek.