Terraphim
v2026.05.18
Terraphim
Home Capabilities How-tos Docs Rust Releases Install Donate

terraphim-agent CLI

Search-first AI agent with knowledge-graph context, session memory, and failure capture

15 April 2026 1 min read 198 words
Capability agent cli ai-agents learning

terraphim-agent is a command-line AI agent that searches before it answers. It runs local knowledge graph queries, imports session history from Claude Code and Cursor, captures failed commands via post-tool-use hooks, and surfaces past corrections when you encounter a recurring error.

Install it with one command:

cargo install terraphim-agent

What it does

  • Session search: query across imported Claude Code and Cursor session logs.
  • Knowledge-graph search: match queries against role-configured Aho-Corasick automata.
  • Learning capture: the learn subcommand records failed commands and their corrections.
  • Command rewriting: pre-tool-use hooks rewrite npm install to bun add, pip install to uv add, etc. via a thesaurus.
  • Learning compile: learn compile converts captured ToolPreference corrections into a thesaurus JSON that the replace command loads directly, closing the feedback loop from failure to live rewrite.
  • Listener dispatch: the listener executes terraphim-agent subcommands triggered by @adf:<agent-name> Gitea mentions, with three security layers (allowlist, metachar rejection, CommandGuard), and posts results back as markdown comments.

See the command rewriting how-to and the blog post Teaching AI Agents to Learn from Their Mistakes for worked examples.