mag-agent 0.14.1

MagAgent — CLI AI coding agent with persistent MagGraph memory. Like the Magpie: intelligent, tool-using, and never forgets.

🐦‍⬛ MagAgent

A terminal-native AI coding agent with persistent memory, built for developers who want an assistant that genuinely learns them.

Quick Start · Providers · Tools · Skills · Memory · Gateway · Docs

---

Why "Mag"?

Mag is short for Magpie — a member of the Corvidae (Corvid) family.

Corvids — crows, ravens, magpies, jays — are among the most cognitively sophisticated animals on Earth. They are renowned for three traits that define what MagAgent aspires to be:

• 🧠 Memory — Corvids remember individual human faces for years and recall the locations of thousands of cached food items. MagAgent remembers your projects, preferences, patterns, and workflows across every session.
• 🔧 Tool Use — Corvids are some of the only non-primate animals that manufacture and use tools. MagAgent wields a rich toolkit: web search, file operations, databases, document generation, HTTP clients, code execution, and more.
• 💡 Intelligence — Corvids pass mirror self-recognition tests and demonstrate future planning. MagAgent plans multi-step tasks, spawns sub-agents for parallel work, and self-improves its knowledge graph over time.

The name also nods to MagGraph — the Rust-powered graph database that backs MagAgent's memory system, storing knowledge as plain Markdown files in Git.

---

What is MagAgent?

MagAgent is a CLI-first AI coding agent that:

• Runs entirely in your terminal, with an optional local operations UI when you want a browser view
• Presents a polished Rich terminal UI with a compact session banner, Markdown response panels, and quieter streaming
• Bridges workbench state into durable MagGraph memory through context maps and explicit memory promotion
• Documents architecture boundaries for memory, workbench, context, tools, CLI/TUI, and compatibility-safe refactors
• Maintains a persistent memory graph per user that grows smarter over time
• Connects to 11+ AI providers (local and cloud) via a single config
• Has 31 built-in tools out of the box — no plugins or configuration required
• Includes 10 pre-built skill libraries for docs, spreadsheets, PDFs, images, video, data analysis, REST APIs, databases, desktop automation, and Git
• Uses token-efficient context management: conversation compaction, repo-map slices, memory/skill budgets, and compressed tool results
• Ships built-in offline documentation and self-help search through magent docs
• Creates restore checkpoints before agent file writes, edits, and deletes
• Discovers project-local test/lint/build commands and reads .magent/config.toml
• Builds a lightweight local code intelligence index for symbols, imports, related files, and targeted tests
• Supports memory quality controls for duplicate review, node merge, and stale-node suppression
• Includes a reliability test harness for the agent loop, provider layer, DB tools, CLI smokes, and packaged docs
• Supports patch-first coding workflows, workspace status reports, project command roles, and release readiness checks
• Supports executable plan records, session-level undo, command learning, saved reviews, and CI repair plans
• Includes a durable local workbench for tasks, artifacts, project profiles, inboxes, routines, follow-ups, API bookmarks, patch queues, session timelines, static dashboards, and a live local UI
• Supports a remote gateway so you can send it tasks from Slack, Discord, or Telegram while you're away from your terminal

Every session, MagAgent extracts facts, preferences, and patterns from your conversation and writes them into a MagGraph knowledge graph. Next session, it reads that graph to understand your tech stack, coding style, project context, and recurring patterns — without you having to repeat yourself.

---

Quick Start

Install

pip install mag-agent

# With gateway support (Slack/Discord/Telegram):
pip install "mag-agent[gateway]"

# Recommended: isolate with pipx
pipx install mag-agent

First-time setup

magent setup

The wizard will:

1. Create a named user profile with an isolated memory graph
2. Walk you through selecting an AI provider and model
3. Test the connection live

Start a session

magent

Quick one-shot task

magent ask "Refactor the auth module to use JWTs and add tests"
magent docs list
magent tutorial
magent doctor

---

Providers

MagAgent uses LiteLLM under the hood, supporting any OpenAI-compatible endpoint.

Provider	Config ID	Notes
Ollama	ollama	Local inference, free, default
Nous Portal	nous-portal	Hermes 4, 200+ curated models
OpenCode Zen	opencode-zen	Coding-optimized models
OpenCode Go	opencode-go	Fast, cost-efficient coding models
OpenAI	openai	GPT-4o, GPT-4.1, o3
Anthropic	anthropic	Claude 3.5 Sonnet / Claude 4
Google	google	Gemini 2.0 / 2.5 Pro
Groq	groq	Ultra-fast inference
OpenRouter	openrouter	200+ model aggregator
LM Studio	lmstudio	Local GUI-managed models
AWS Bedrock	bedrock	Enterprise / VPC
Custom	custom	Any OpenAI-compatible endpoint

Configure multiple providers and switch mid-session: /model anthropic/claude-3-5-sonnet

---

Tools

MagAgent ships with 31 built-in tools the agent can call without any setup.

File & Code Tools

Tool	Description	Permission
read_file	Read file preview, with truncation for large files	Silent in project, confirm outside
read_file_range	Read exact line ranges from a file	Silent in project, confirm outside
outline_file	Compact source outline with symbols and line numbers	Silent in project, confirm outside
write_file	Write/create a file	Auto in project dir
edit_file	Replace exact string in file	Auto in project dir
delete_file	Delete file or directory	Confirm
list_dir	List directory contents	Silent in project, confirm outside
diff_files	Unified diff between two files	Silent in project, confirm outside
compress	Zip or tar.gz a file/directory	Auto
extract	Unzip/untar an archive	Auto
run_shell	Execute a shell command	Tiered by command risk
run_python	Run Python code in isolated subprocess	Confirm
install_package	pip install with user permission	Confirm
search_codebase	Ripgrep pattern search	Silent
git_op	Any git subcommand	Tiered

Web & Network Tools

Tool	Description	Permission
web_search	DuckDuckGo search (real results, no API key)	Auto
web_fetch	Fetch URL, clean article extraction via trafilatura	Auto
http_request	Full HTTP client: GET/POST/PUT/PATCH/DELETE	Auto

Data Tools

Tool	Description	Permission
json_query	JMESPath query over JSON file or string	Silent
db_query	SELECT from a named SQLite database	Silent
db_execute	INSERT/UPDATE/DELETE/CREATE TABLE	Auto
db_list_tables	List tables + row counts	Silent
db_schema	Show column definitions for a table	Silent
db_list_databases	List all user databases	Silent

System & Desktop Tools

Tool	Description	Permission
system_info	CPU, RAM, disk, OS, Python version	Silent
notify	Desktop notification (plyer / notify-send)	Silent
clipboard_read	Read system clipboard	Silent
clipboard_write	Write to clipboard	Auto
open_file	Open file in default application (xdg-open)	Auto
read_image	Image metadata + base64 for vision models	Silent in project, confirm outside

---

Permission Modes

MagAgent uses a 4-tier risk system to auto-approve safe operations and only ask when it matters.

Mode	Behaviour
balanced (default)	Project reads run; outside-project reads confirm; low-risk writes auto-run; medium needs Enter; high needs typed "yes"
silent	Only destructive or high-risk ops prompt
paranoid	Everything except file reads requires confirmation
yolo	Fully autonomous — no prompts

magent mode balanced   # Set globally
/mode paranoid         # Change in-session

Pre-approve patterns in your config (e.g. trust all git and pytest commands):

[permissions]
allowed_shell_patterns = ["git *", "npm *", "pytest *", "cargo *"]

---

Memory Graph

MagAgent's memory is powered by MagGraph — a Rust-backed in-process graph database that stores nodes as plain Markdown files in a Git repository.

~/.config/magent/users/<username>/memory/
├── preference_uses_typescript.md
├── project_ecommerce_backend.md
├── pattern_prefers_async_await.md
└── ...

Node types:

Type	What it stores
preference	Coding style, tool choices, formatting preferences
project	Projects you work on, their tech stack and structure
pattern	Recurring problems and solutions MagAgent has learned
skill_learned	Techniques and APIs you've used together
fact	Domain knowledge extracted from conversations
session_summary	High-level summaries of past sessions
error_pattern	Bugs and their resolutions
bookmark	URLs and references the agent saved for you

Memory is extracted and written every N turns (configurable, default 5) and always at session end.

magent memory stats                     # Node/edge counts, disk usage
magent memory index                     # Build/update semantic search sidecar
magent memory search "JWT"              # Hybrid semantic + keyword search
magent memory search --semantic "JWT"   # Force semantic search
magent memory search --keyword "JWT"    # Force keyword/full-text search
magent memory semantic status           # Inspect semantic sidecar status
magent memory semantic reset            # Reset semantic sidecar
magent memory show project_myapp        # View a node
magent memory traverse project_myapp    # BFS from a node
magent memory review --diff             # Audit pending memory graph changes
magent memory approve                   # Commit reviewed memory graph changes
magent memory quality                   # Find duplicate-looking/suppressed nodes
magent memory merge <target> <source> --preview # Preview duplicate memory merges
magent memory merge <target> <source>   # Merge duplicate memory nodes
magent memory suppress <node-id>        # Mark stale memory suppressed
magent memory unsuppress <node-id>      # Remove suppression markers
magent memory ui                        # Open MagGraph dashboard
magent memory sync status               # Run MagGraph sync status
magent memory export --out backup.json  # Export all nodes as JSON
magent memory reset                     # Wipe all memory (with confirmation)

Token-Efficient Context

MagAgent keeps context lean while preserving useful state:

• Conversation compaction summarizes older turns and keeps recent turns verbatim.
• Repository map slices inject relevant file/symbol maps instead of whole files.
• Memory recall budgets inject compact matches first, then a few excerpts.
• Semantic memory search stores local SQLite embedding sidecars, uses Ollama embeddings when available, and falls back to deterministic offline vectors.
• Selective tool injection sends a compact relevant tool subset to the model each turn instead of always injecting every built-in tool.
• Skill budgets truncate long skill guidance before it crowds out the task.
• Tool result compression trims large outputs and points the agent to targeted follow-ups.
• Stale result pruning removes old file-read results from live context after files are edited.
• Tool output budgets cap oversized tool results with a raw=true escape hatch.
• Large file reads return previews; use outline_file and read_file_range for exact context.

---

Local Workbench

MagAgent's workbench stores practical productivity state under each user profile:

• Task ledger — magent task add/list/done/report
• Artifact workspace — magent artifact add/list
• Project profiles — magent project profile/list/commands/roles/doctor/config/command-history/command-promote
• Code intelligence — magent code index/symbols/related
• Test intelligence — magent test map/related/explain/run-related
• Inbox and routines — magent inbox add/triage, magent routine add/run
• Follow-ups — magent followup add/list
• Knowledge commands — magent knowledge remember/recall/forget
• Review and planning — magent plan --save, magent plan-exec, magent plan-preview, magent plan-run, magent plan-list, magent plan-show, magent plan-apply, magent plan-discard, magent review --json, magent review --save, magent review-show, magent run
• Repo/test helpers — magent graph, magent code index/symbols/related, magent test map/related/explain/run-related, magent test-intel, magent env-doctor, magent diagnostics, magent ci --logs, magent ci --repair-plan --save
• Patch queue — magent patch save/list/apply/revert
• Patch-first workflow — magent patch preview/explain, magent workspace status/clean-report
• Checkpoint undo — magent checkpoint list/show/diff/restore/restore-last/session-list/session-diff/session-restore
• Built-in docs — magent docs list/show/search/doctor/generate-reference
• Artifact registry — magent artifact add/list/show/open/checksum
• Data/API/notes — magent data inspect, magent api save/list, magent notes
• Session and usage — magent session timeline, magent stats, magent dashboard, magent dashboard --serve, magent ui

Workbench files are plain JSON in ~/.config/magent/users/<username>/workbench/.

---

SQLite Local Databases

The agent can create and manage structured local databases — per user, per project, or user-specified.

~/.config/magent/users/<username>/databases/
├── default.db       # General-purpose
├── myproject.db     # Project-specific
└── analytics.db     # Purpose-specific

Inside a session, the agent automatically uses these tools to store structured data — task lists, research caches, API test logs, contacts — without any setup required.

/db    # In-session: list your databases

---

Skills

Skills are Markdown files that teach the agent how to perform specific tasks — code patterns, library usage, common pitfalls, and decision guides. They are injected into context automatically when relevant.

Locations

• Global: ~/.config/magent/skills/<skill-name>/SKILL.md
• Project-local: .magent/skills/<skill-name>/SKILL.md

Built-in Skills Library

MagAgent ships with 10 pre-built skills in docs/skills/:

Skill	Triggers On	Guide
Create Word Docs	docx, word document, report	python-docx + docxtpl
Create Spreadsheets	excel, xlsx, spreadsheet	openpyxl with charts/formulas
Create PDFs	pdf, html to pdf	fpdf2 + WeasyPrint + pypdf
Create Images	image, chart, plot, PNG	Pillow + matplotlib
Create Video/Audio	video, audio, mp4, Remotion	Remotion (React) + moviepy + ffmpeg
Data Analysis	pandas, csv, dataframe	pandas + SQLite integration
REST API Testing	api, http, endpoint, curl	http_request patterns + auth
SQLite Database	sql, database, sqlite	Named DBs, common schemas
Desktop Automation	notify, clipboard, open file	notify + clipboard + system info
Git Workflow	git, branch, commit, merge, rebase	Git best practices & conflict resolution

Writing Your Own Skill

---
name: my-skill
description: Brief description — used for matching
version: "1.0"
trigger_keywords:
  - keyword1
  - keyword2
tools_required:
  - run_shell
  - write_file
---

# Skill Title

Guidance for the agent here — code patterns, library usage, pitfalls...

---

Sub-Agents

Spawn a parallel agent to work on a focused sub-task while you continue the main conversation:

/spawn Write unit tests for all functions in src/auth.py

The sub-agent runs an isolated session sharing your memory graph, completes the task, and returns a summary. Use this for long-running tasks that shouldn't interrupt the main flow.

---

Remote Gateway

Send tasks to MagAgent from Slack, Discord, or Telegram while you're away from your terminal.

# Install gateway dependencies
pip install "mag-agent[gateway]"

# Generate config template
magent gateway init

# Start (background daemon)
magent gateway start

# Platform-specific
magent gateway start slack
magent gateway start discord telegram

# Monitoring
magent gateway status
magent gateway logs --follow
magent gateway stop

How it works

When you message the bot:

1. It immediately replies "⏳ Working on it..."
2. Runs your task through the full agent (tools, memory, etc.)
3. Edits that message with the result when done
4. Sessions are persistent per channel — it remembers conversation context

Security

• Allowlist — only users in allowed_user_ids can send instructions
• Channel restriction — optionally limit to specific channels
• Rate limiting — configurable per-user request limit (default 10/min)
• Task timeout — configurable max execution time (default 5 min)

Setup Guides

Platform	Guide	Notes
Slack	setup-slack.md	Socket Mode — no public URL needed
Discord	setup-discord.md	Bot token — free, 2-minute setup
Telegram	setup-telegram.md	@BotFather — simplest of the three

---

All Commands

User Management

magent user create <name>   # Create a user profile
magent user switch <name>   # Switch active user
magent user list            # List all users
magent user delete <name>   # Delete user + memory (with confirmation)
magent user current         # Show active user

Memory

magent memory stats                      # Node/edge counts, disk usage
magent memory search "<query>"           # Search memory graph
magent memory show <node-id>             # View a memory node
magent memory traverse <node-id>         # BFS traversal from a node
magent memory delete <node-id>           # Delete a node
magent memory export --out backup.json   # Export all nodes as JSON
magent memory reset                      # Wipe all memory (prompts "yes")
magent memory log                        # View recent session logs
magent memory ui                         # Open embedded MagGraph UI
magent memory sync status                # Git sync status via MagGraph
magent memory sync pull                  # Pull memory graph updates
magent memory sync push -m "message"     # Commit/push memory graph updates

Gateway

magent gateway init              # Print example config
magent gateway start             # Start all configured platforms (daemon)
magent gateway start slack -f    # Single platform, foreground mode
magent gateway stop              # Stop daemon (SIGTERM)
magent gateway status            # Is daemon running? PID?
magent gateway logs [-n N] [-f]  # View / follow gateway log

Other

magent setup           # First-run setup wizard
magent mode <mode>     # Set permission mode globally
magent doctor          # Health check: providers, memory, deps
magent plan "goal"     # Generate a local implementation plan
magent run "goal"      # Record an autonomous work-session plan
magent review          # Heuristic local diff review
magent graph           # Lightweight repo import graph
magent code index      # Build local symbol/import/test index
magent code symbols    # Search indexed code symbols
magent code related    # Show related tests/import peers for a file
magent test map        # Map source files to likely tests
magent test related    # Show likely tests for a file
magent test explain    # Explain why tests were selected
magent test run-related # Run likely tests for a file
magent test-intel      # Suggest tests for current git changes
magent patch preview   # Preview a saved patch
magent patch explain   # Explain patch impact
magent workspace status # Show git/workbench status
magent release check   # Run release readiness checks
magent env-doctor      # Project environment checks
magent dashboard       # Export static local dashboard
magent ui              # Serve live local operations UI
magent --version       # Show version

In-Session Slash Commands

Command	Description
/help	All slash commands
/memory	Memory graph stats
/skills	Loaded skills list
/model	Current model / change model
/user	Active user
/mode <mode>	Change permission mode
/spawn <task>	Spawn a sub-agent
/db	List your SQLite databases
/clear	Clear conversation history
/exit	End session

---

Configuration

Full config at ~/.config/magent/config.toml:

[defaults]
provider = "ollama"
model = "qwen2.5-coder:32b"
permission_mode = "balanced"
context_window_tokens = 32000
memory_budget_tokens = 4000
repo_map_budget_tokens = 1200
skill_budget_tokens = 2000

[memory]
write_every_n_turns = 5
extraction_provider = "ollama"
extraction_model = "qwen2.5:7b"
encrypt = false
recall_body_tokens = 220

[models]
coding = "openai/gpt-4.1"
review = "anthropic/claude-sonnet-4"
memory = "ollama/qwen2.5:7b"
cheap = "opencode-go/deepseek-v4-flash"
fallback = ["ollama/qwen2.5-coder:32b"]

[context]
compact_every_n_turns = 10
keep_recent_turns = 6
max_history_tokens = 6000

[permissions]
mode = "balanced"
allowed_shell_patterns = ["git *", "npm *", "pytest *"]

[providers.ollama]
base_url = "http://localhost:11434"
default_model = "qwen2.5-coder:32b"

[providers.nous-portal]
base_url = "https://inference-api.nousresearch.com/v1"
api_key_env = "NOUS_API_KEY"
default_model = "nous-hermes-4"

[providers.opencode-go]
base_url = "https://opencode.ai/go/v1"
api_key_env = "OPENCODE_GO_API_KEY"
default_model = "deepseek-v4-flash"

[gateway]
username = "alex"
allowed_user_ids = ["YOUR_SLACK_USER_ID"]
rate_limit_per_minute = 10
max_task_duration_seconds = 300

[gateway.slack]
bot_token = "xoxb-..."
app_token = "xapp-..."

[gateway.discord]
bot_token = "..."

[gateway.telegram]
bot_token = "..."

---

Documentation

Document	Description
docs/skills/create-word-docs/SKILL.md	Word document generation (python-docx, docxtpl)
docs/skills/create-spreadsheets/SKILL.md	Excel spreadsheet generation (openpyxl)
docs/skills/create-pdfs/SKILL.md	PDF generation (fpdf2, WeasyPrint, pypdf)
docs/skills/create-images/SKILL.md	Image manipulation (Pillow, matplotlib)
docs/skills/create-video-audio/SKILL.md	Video/audio (Remotion, moviepy, ffmpeg)
docs/skills/data-analysis/SKILL.md	Data analysis (pandas, SQLite)
docs/skills/rest-api/SKILL.md	REST API testing and integration
docs/skills/sqlite-database/SKILL.md	SQLite database patterns
docs/skills/desktop-automation/SKILL.md	Desktop notifications, clipboard, system info
docs/skills/git-workflow/SKILL.md	Git workflows & conflict resolution
docs/gateway/setup-slack.md	Slack gateway setup (Socket Mode)
docs/gateway/setup-discord.md	Discord gateway setup
docs/gateway/setup-telegram.md	Telegram gateway setup

---

Development

git clone https://github.com/AlexMercedCoder/MagAgent.git
cd MagAgent
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=src/magent --cov-report=term-missing

# Lint
ruff check src/

# Built-in docs coverage
magent docs doctor

# Type check
mypy src/magent

Project Structure

src/magent/
├── agent.py          # AgentSession — tool loop, streaming, sub-agents
├── cli/main.py       # Typer CLI entry point
├── config/           # TOML config, user profiles
├── gateway/          # Remote gateway (Slack, Discord, Telegram)
│   └── adapters/     # Platform-specific adapters
├── memory/           # MagGraph integration — read, write, search
├── permissions/      # Risk tiers, auto-approve logic
├── providers/        # LiteLLM provider registry
├── repo_map.py       # Token-efficient repository map cache
├── skills/           # SKILL.md discovery, matching, lockfile
├── subagents/        # Sub-agent runner
├── tokens.py         # Lightweight token budgeting helpers
├── tools/            # 31 built-in tools (file, web, db, system)
│   ├── executor.py   # ToolExecutor implementation
│   └── db.py         # SQLite named database tools
├── context.py        # Context map and memory promotion bridge
├── workbench.py      # Local productivity ledgers and workflow helpers
├── workbench_store.py # JSON-backed workbench storage primitive
├── logging.py        # JSONL session event logging
├── setup.py          # First-run wizard
└── tui.py            # Rich terminal UI, theme, status, and streaming renderer
docs/
├── gateway/          # Gateway setup guides
└── skills/           # Built-in skill SKILL.md files
tests/
└── unit/             # 162 unit tests (all mocked, no credentials needed)

---

License

Apache 2.0 — see LICENSE

---

Built with 🐦‍⬛ by Alex Merced · Powered by MagGraph

Like the Magpie — intelligent, tool-using, and never forgets.