I gave my AI coding agent a Brain, Hands, and Eyes: Introducing CtxNest

AI coding assistants are incredible. They can refactor your spaghetti into... slightly more organized spaghetti. They can explain code they've never seen. They can confidently suggest solutions that are almost correct.

What they can't do is remember anything. Close the tab, and your AI goldfish starts fresh. Every. Single. Time.

I got tired of it. So I built CtxNest — a persistent Brain for knowledge, a sandboxed pair of Hands for action, and Eyes for feedback that closes the loop. All over MCP. All on your own machine. No cloud, no subscription, no vendor with access to your codebase.

The problem with "just paste more context"

You know the ritual. Open a new chat. Paste the README. Paste the relevant file. Explain the architecture again. Paste the error. Explain what you already tried. Watch the AI confidently suggest the exact thing you told it not to do two messages ago.

A code suggester answers a question. An agent closes a task. The difference is a feedback loop — and almost no tool has one.

CtxNest builds that loop locally.

Brain → Hands → Eyes

Brain → Hands → Eyes → Brain → ...

Brain answers what does the agent need to know? — a markdown knowledge vault with FTS5 full-text search, git-backed versioning per file, surgical section edits, and cross-project context. Think Obsidian, but your AI can actually read it without you copy-pasting things into a chat window at 11pm.

Hands answers what can the agent safely do? — you declare commands in a ctxnest.json, CtxNest exposes them as namespaced MCP tools. No shell. Locked working directory. Clean environment. Validated params. Hard timeout. Optional human approval. The agent can't invent tools, escape the project root, or modify its own command surface. It can only do what you said it could do. Revolutionary concept, I know.

Eyes answers what just happened? — Hands' formatted stdout, Brain's diff_against_disk / whats_new / get_history for diff-aware observation, and journal_append to write learnings back into Brain so the next session starts smarter than this one.

That last part — the Journal arrow back to Brain — is what makes it compound. The agent documents what it did, and tomorrow's session finds that note. The loop gets smarter every run. Your AI goes from goldfish to something with actual long-term memory.

A real example

You ask Claude Code: "Convert the demo video to the right format for the target app."

No preamble. No "here's the project structure." Just that sentence.

1. Brain (context gathering)

• search("target app video format") → finds standards.md: target app requires H.264 MP4
• search("demo video source") → finds media-assets.md: source is assets/raw/demo_raw.mov

2. Hands (execution)

• Calls myproj__convert-video with the resolved paths
• Runs ffmpeg safely in your project root — no shell injection, no creative path traversal, no excitement

3. Eyes (verification)

• Reads stdout, confirms conversion succeeded, checks file size and duration

4. Brain (journaling)

• journal_append: "Converted demo_raw.mov to H.264 MP4. Final size: 14.2MB."

One prompt. The agent pulled context, acted, verified, and documented. Tomorrow it already knows this was done and how it went.

If convert-video had confirm: true in ctxnest.json, step 2 pauses for your approval first. Because sometimes "just let the AI run ffmpeg on your files" is not the vibe.

How it stacks up

Every other agentic coding tool ships with execution baked in. None have a knowledge base. None carry context across projects. None let you define the command surface.

Execution is a commodity at this point. Every coding agent has it. The gap is everything around execution: persistent memory, cross-project standards, and a command surface you author and review like infrastructure — not one a vendor decided for you.

And because it's all local:

• Deterministic retrieval — SQLite FTS5, not fuzzy vector embeddings. No hallucinated relevance for your class names and function signatures.
• History-aware — agents can reason over the history of your decisions, not just today's snapshot. "What did we decide about auth last month?" actually works.
• Zero token waste — agents browse before they pull. Context window stays clean instead of stuffed with your entire docs folder.
• Security by construction — no credentials pre-staged in a remote sandbox, no multi-tenant blast radius, no data egress to a third party. Kill switch is Ctrl-C on your own process. The threat model is refreshingly boring.

Getting started

Docker is the fastest path:

curl -fsSL https://raw.githubusercontent.com/safiyu/ctxnest/main/docker-compose.hub.yml \
  | docker compose -f - up -d

UI at http://localhost:3000. Data persists in ./ctxnest-data.

Prefer MCP-only, no Docker? Drop this in your client's mcpServers.json:

{
  "mcpServers": {
    "ctxnest": {
      "command": "npx",
      "args": ["-y", "ctxnest-mcp"],
      "env": {
        "CTXNEST_DATA_DIR": "/absolute/path/to/your/data"
      }
    }
  }
}

Works with Claude Code, Cursor, Gemini, Codex, and anything else that speaks MCP.

See it in action

Full walkthrough demo covering the Brain → Hands → Eyes loop, live MCP integration with Claude and Antigravity, knowledge vaulting, and local RAG — watch it here.

Want to poke the MCP endpoints without installing anything? No-install interactive demo on the CtxNest page on Glama.

⭐ github.com/safiyu/ctxnest

This is v7.2.2. The Hands feature landed in v7.0.0 and it's where things got genuinely fun. Give it a spin, file issues, tell me what's broken.

Built with care for the future of agentic coding. And mild frustration at AI goldfish memory.