andrew@thecoder:~$

$ Enchanter

View on GitHub →  ·  Runs on Linux, macOS, and Windows.

A focused AI agent harness. Single Rust binary, any OpenAI-compatible provider, zero runtime dependencies. Reads your SOUL, loads your memory, finds your skills, talks to your model. Nothing more.

### features

• - Single Binary — No runtime dependencies. Build it, ship it, run it anywhere.
• - Any OpenAI-Compatible Provider — Works with OpenAI, Ollama, OpenRouter, Groq, or any provider that speaks the OpenAI API.
• - Named Providers — Define multiple providers in config.yaml and switch between them mid-session with /model.
• - SOUL-Driven Personas — Define your agent's personality, directives, and behavioral constraints in SOUL.md.
• - Knowledge Store — Structured key-value facts that persist across sessions. Unlike memory (narrative text), knowledge entries are typed, searchable, and organized by category. The agent learns once and never asks again.
• - Persistent Memory — Memories persist across sessions with automatic summarization when the store grows.
• - Session Summaries — On clean exit, Enchanter generates a concise session summary and saves it to memory so your next session picks up where you left off.
• - Session History — Every conversation is automatically logged to JSONL files. List and review past sessions with enchanter sessions or /sessions in the REPL.
• - Prompt Inspection — See exactly what the model receives. /prompt budget shows token/character counts per layer; /prompt diff shows changes between turns. enchanter prompt --budget and --diff from the CLI.
• - Session Recording & Replay — Record sessions to JSONL with --record, then replay with enchanter replay. Swap models, verify determinism, or replay with stubbed tools. API keys are redacted by default.
• - Skill Discovery — Drop in SKILL.md files to teach your agent new capabilities. Compatible with the agentskills.io format.
• - MCP Integration — Connect local (stdio) and remote (HTTP) MCP servers for external tools and data.
• - Built-in Tools — exec_command, read_file, write_file, edit_file, search_files, list_directory, memory, knowledge.
• - Interactive REPL — Full readline-powered REPL with slash commands for soul, memory, skills, config, and more.
• - Daemon Mode — Background process keeps MCP servers warm, eliminating 3–15s cold starts. Linux & macOS only.
• - TUI Mode — Multi-pane terminal UI with sidebar (skills + memory), chat area, and input bar. Keyboard-driven, all REPL slash commands work.
• - Security Sandbox — On Linux, exec_command runs under a Landlock kernel sandbox confined to allowed paths. File tools check the path allowlist on all platforms.
• - Context Compaction — Rolling compaction keeps long sessions within the model's context window. Older turns are summarized; recent turns are always preserved verbatim.

### philosophy

### platform support

Daemon mode requires Unix domain sockets and is only available on Linux and macOS. On Windows, Enchanter runs entirely in inline mode — no --no-daemon flag or daemon subcommand is available.

### getting started

### configuration

All config lives in ~/.enchanter/config.yaml. Environment variables override config values. First run creates sensible defaults.

### named providers

Define multiple providers in config.yaml and switch between them mid-session. Each provider can set model, base_url, and api_key. Fields left blank inherit from the top-level model config or environment variables.

### soul, memory & skills

The system prompt is assembled in seven layers, each with a distinct role:

• 1. SOUL — Your agent's persona from SOUL.md. Stable across turns, defines identity and behavioral directives.
• 2. CONTEXT — Environment info: model, user, working directory, host, platform.
• 3. SKILLS — Discovered SKILL.md files index.
• 4. INSTRUCTIONS — Tool usage guidance, canonical tool descriptions, and knowledge capture directives.
• 5. KNOWLEDGE — Structured key-value facts from the knowledge store. Compact and searchable.
• 6. VOLATILE — Memory entries and user profile. Changes frequently, fully replaceable.
• 7. SESSION — Current date and session start timestamp.

### knowledge store

Unlike memory (free-form narrative text), the knowledge store captures discrete, typed facts that persist across sessions. Keys use dot-namespaced identifiers like project.rust_version or user.email. Values are short strings organized into five categories:

• - environment — Runtime and system facts (OS, shell, tool versions)
• - project — Project-specific details (language, framework, conventions)
• - preference — User preferences and style (code style, commit conventions)
• - decision — Architectural or design decisions (chosen approach, rationale)
• - fact — General facts that don't fit other categories

Each entry tracks its source: observed (detected from tool output), told (explicitly stated by the user), or inferred (concluded by the agent from context).

The agent proactively stores facts it discovers during conversation. When it learns a version number, a project path, a user preference, or a bug workaround, it stores it with the knowledge tool so it never has to ask again. The INSTRUCTIONS prompt layer directs this behavior automatically.

### session continuity

When you exit the REPL with /exit or Ctrl+D, Enchanter generates a concise summary of your session and saves it to memory. Your next session automatically loads this context so you can pick up where you left off.

• • Skipped for single-shot mode (-p flag)
• • Skipped if the session was too short (no real exchange)
• • 10-second timeout; falls back to a simple message count on failure
• • Disable with summarize_on_exit: false in config.yaml

session history

Every conversation is automatically saved to ~/.enchanter/sessions/ as a JSONL file. Each message is appended atomically — if the process crashes, everything written up to that point is preserved. Each session gets a unique ID and stores the model, timestamps, and full conversation including tool calls and results.

### prompt inspection

Enchanter assembles the system prompt in explicit layers: SOUL → CONTEXT → SKILLS → INSTRUCTIONS → KNOWLEDGE → VOLATILE → SESSION. You can inspect exactly what the model receives and how it changes between turns.

The budget view shows approximate token counts per layer (chars÷4 heuristic), visual bar charts, and threshold warnings when a layer exceeds ~4,000 estimated tokens.

The diff output highlights layer-level changes — memory blocks added/removed, skill index changes, tool list changes, provider/model changes, and SOUL changes. API keys and auth headers are never shown in diff output.

### recording & replay

Record full sessions to JSONL files for debugging, reproducibility, and model comparison. API keys and auth tokens are never included in recordings by default.

Each recorded event includes a schema version, monotonic sequence number, UTC timestamp, and a typed payload. Recordings capture config snapshots (with redacted API keys), prompt layer hashes, user messages, assistant responses, tool calls, model changes, and session summaries.

### mcp servers

Connect external tools and data sources via Model Context Protocol servers. Two transport types are supported:

• - stdio — Local processes spawned by Enchanter. Auto-restarted on crash (up to 3 attempts).
• - HTTP — Remote servers via Streamable HTTP with SSE support. Session tracking with Mcp-Session-Id headers.

Tools from MCP servers are namespaced as server_name:tool_name. Use /tools in the REPL to list all available tools.

### security sandbox

On Linux, exec_command (shell execution) runs under a Landlock kernel sandbox that confines the spawned shell to an allowlist of directories. The sandboxed process can read/write within allowed_paths and read/execute system directories (/usr, /bin, /lib, etc.), but write access to system dirs is denied.

File tools (read_file, write_file, edit_file, search_files, list_directory) check allowed_paths on all platforms.

### context compaction

For long sessions, the conversation window can grow beyond the model's context limit. Rolling compaction keeps the live context within bounds:

When the estimated token count exceeds max_tokens, older turns are summarized into a single compact message. The most recent keep_last_turns messages are always preserved verbatim. Both values are optional — without them, no compaction occurs and the full conversation is sent.

### tui mode (optional feature)

The terminal UI provides a multi-pane interface with a sidebar (skills + memory), main chat area, and input bar. A header shows the model, provider, and session info; a footer shows tool/skill counts and quick key hints.

All REPL slash commands work in the TUI (/help, /clear, /model, /undo, /retry, etc.). On exit, the TUI generates a session summary to memory just like the REPL.

The TUI is enabled by default. Build without it: cargo build --no-default-features.

### daemon mode (Linux & macOS only)

### running

### repl commands

### environment variables

All optional. Environment variables override config.yaml values.

Provider api_key and base_url fields support ${VAR} expansion, so you can write api_key: ${OPENROUTER_API_KEY} instead of hardcoding.

### data directory

By default, all data lives in ~/.enchanter/. Set ENCHANTER_HOME to point it elsewhere. First run auto-creates the directory with defaults.