MagAgent

What it is

MagAgent is a terminal-native agent framework in Python, Apache 2.0 licensed. It handles coding and general productivity work: reading and editing files, running commands, searching the web, querying databases, generating documents, and orchestrating multi-step tasks.

Two things distinguish it. Memory is a first-class component backed by a graph store that persists between sessions, not a session buffer. And agents are defined as portable profile documents rather than as configuration inside the tool.

The name is short for magpie, a corvid. The family is known for memory, tool use, and problem solving, which is a reasonable summary of what I wanted the thing to be.

The memory-first bet

The problem I built this around is the one every agent user recognizes. You explain your conventions, your architecture, and the three unusual decisions and why they were made. The session ends. Next time you explain them again.

The approaches I tried before this all broke somewhere. Putting everything in the system prompt does not scale, because context is finite and a growing prompt dilutes the task. Summarizing conversations loses specifics, and specifics are usually the valuable part. Retrieval over past transcripts finds what was said rather than what was concluded, and gets worse as the store grows.

MagAgent uses a persistent knowledge graph instead. Facts, decisions, and observations become nodes with relationships, stored as Markdown in a repository and versioned by Git. Retrieval pulls a connected subgraph rather than a similarity-ranked list of fragments, which returns connected context instead of isolated snippets.

The design decision I feel most strongly about is that promotion into memory is explicit rather than automatic. This is counterintuitive and I am confident it is right. Memory that accumulates by default fills with noise, and noise competes in every future retrieval, so the system gets worse the more you use it. Requiring a deliberate promotion with a reason means memory grows slower and stays useful, and everything in it can be questioned because it was put there on purpose.

The Mag ecosystem

MagAgent is one of three related projects, and the separation is deliberate.

• MagGraph is the memory layer: Rust-backed, Markdown nodes, Git-versioned, with its own Python API and a generated protocol server.
• MagAgent is the harness: the loop, tools, providers, and terminal experience.
• Mag Command Center is a cross-platform desktop application for projects, chat, configuration, memory, and plugins.

Keeping memory in its own project is the part that matters architecturally. Memory is the artifact that cannot be recreated, and trapping it inside a runtime means changing runtimes costs everything the agent learned, which means you will not change runtimes. Because MagGraph exposes a protocol server, another agent entirely can read the same memory. That is the layering this site argues for, applied where it counts most.

Agents as profiles

MagAgent implements the Open Agent Profile specification at Level 3, storing agent definitions as files in the project or user directory rather than as internal configuration.

A profile describes a named agent: role and instructions, model or capability tier, tools it may reach, permissions, and what previous sessions learned. Profiles support inheritance, so a specialized agent derives from a general one and narrows its capabilities, with narrowing the only permitted direction.

Three consequences follow, and they are why I bothered.

Review. A profile is a file. Someone who does not write Python can read it, diff it when it changes, and require it to pass review. Authority scattered through code cannot be audited because there is nothing to look at.

Sharing. A useful agent becomes a file a colleague can copy. The reviewer that knows your conventions moves between machines and between people.

Portability. Because the format is a published specification, another conformant harness reads the same profile. Running two harnesses becomes a configuration detail rather than a duplication problem.

Tools, language servers, and MCP

MagAgent has a broad built-in tool surface covering files, shell, web search, HTTP, databases, and document generation, extended in two directions worth separating.

Language servers. It runs real language server clients for Python, TypeScript and JavaScript, Rust, and Go, giving the agent actual symbol knowledge: definitions, references, diagnostics, hover, and rename. This replaces inference over text with lookup against a parsed project. The general principle is that a specific tool answering a question directly beats a general tool the model has to reason through, and symbol lookup is the clearest case of it I know.

MCP. It connects to protocol servers over stdio and streamable HTTP, with catalogs of tools, prompts, and resources that invalidate when servers change. Integrations written once as servers are reachable without harness-specific work, which is the protocol doing its job.

That combination is the shape I think an open harness should have. Deep native integration where the harness is the natural place for it, and a protocol boundary for everything else, so the tool ecosystem is not something the harness has to own.

Skills, recipes, and plugins

Capability arrives through three mechanisms that solve different problems, and separating them keeps each one honest.

Skills are portable folders of instructions loaded when relevant. This is knowledge: how to do a thing, in prose, reviewable by whoever owns the process.

Recipes are saved reusable workflows for repeated operations such as release preparation, bug triage, documentation audits, dependency upgrades, and test repair. This is procedure with parameters, closer to a script.

Plugins bundle agents, recipes, skills, tools, and MCP configuration, with importers that normalize assets from several other agent ecosystems into MagAgent-native form.

That importing capability is the one I would highlight. Treating the wider ecosystem as a source rather than as competition means a team's existing procedures do not have to be rewritten to be usable here. If interoperability is the argument, importing other people's formats is where you demonstrate it rather than only claim it.

Graphs for planned work

MagAgent supports the Agentic Graph Specification, so a multi-step piece of work can be described as a document before it runs: nodes with briefs, typed inputs and outputs, success conditions, capability tiers, required tools and permissions, and human approval gates.

The value is that the plan is reviewable before tokens are spent. An ordinary agent decomposes work internally, and by the time you see the decomposition the work is done. Writing it first moves review to where it is cheap.

This is not right for everything. Conversational and exploratory work has no useful structure to write down, and forcing it into nodes produces a document that is wrong by the second step. Processes with branches, approval points, and consequences do have structure, and those are exactly the ones where an unreviewed plan is expensive.

Sandboxes and scoping

Saved plans and recipes can run inside sandboxes: a Git worktree, a copied workspace, or a Docker container. Each is a different point on the isolation and convenience curve.

A worktree isolates changes from your working directory while sharing the repository, which suits parallel agent work on one project. A copied workspace isolates further at the cost of disk and setup. A container isolates the process, which is the option that bounds what a shell command can reach.

Alongside sandboxes, profiles carry permissions and capability scoping, so a tool surface can be narrowed per profile rather than being global. This matters more than it sounds given the breadth of the built-in tools: tool selection quality degrades as the list grows, so scoping per profile is a quality improvement as much as a safety one.

Background work

A daemon queues background work: asks, recipes, plans, shell tasks, follow-ups, and tasks arriving through a gateway. This is structural rather than a convenience.

An agent that only runs while someone watches can only answer. An agent with a queue can accept work now and finish it later, retry what failed, act on a schedule, and pick up a thread from a previous session. The difference is between a tool you use and a process that runs.

It also raises the stakes on three things the interactive case tolerates. Bounded steps and spend, because nobody is watching the wrong turn. Durable state, because a restart should not lose the work. And a record complete enough to reconstruct what happened while you were away, because there is no memory of it other than what was written down.

Evaluation built in

MagAgent includes isolated evaluation suites with independent validators, timing and token metrics, and reproducible offline and live-provider reports, plus separate evaluations for memory quality.

The memory evaluations are the unusual part and they exist because memory fails silently. Recall returns something plausible but stale. Two contradictory facts both surface. The retrieved subgraph is large enough to crowd out the task. None of these produce an error. They produce gradually worse answers that get attributed to the model.

Measuring precision, staleness, contradiction, provenance coverage, and the token cost of recall turns those into numbers. A memory-first design creates that risk for itself, so shipping the measurement alongside the feature seemed like the minimum honest thing to do.

What daily use actually looks like

Feature lists are a poor description of a tool you use every day, so here is the honest version of how this gets used and what makes the difference between it being useful and being noise.

The first week is worse than a stateless agent

Memory has no content yet, and promotion feels like overhead for no return. This is the point where most people would turn it off. The return arrives around week three, when the agent stops needing to be told the same three things about a project, and it compounds from there. Knowing that in advance is most of what makes it survivable.

Configure providers by role, not globally

Setting a strong model for planning and a small fast one for classification and routing changes both cost and latency substantially, and it is a configuration step rather than an architectural one. Most people set one model and never revisit it, which means every trivial decision runs through the expensive path.

Write the project playbook early

Conventions, architectural boundaries, and things that look wrong but are deliberate belong in a file the agent reads rather than in a correction repeated every session. This is the same instinct as documentation, with a consumer that actually reads it, and it removes a surprising share of the friction people attribute to the model.

Commit in small pieces

Reviewing a hundred-line change is straightforward. Reviewing eight hundred lines produced in one session is not, and review is where correctness is actually established. Small commits also give a clean revert point when a direction turns out to be wrong.

Read the memory occasionally

It is Markdown in a repository. Skimming it monthly catches facts that went stale, conclusions drawn from a single ambiguous case, and duplicates that should be merged. Ten minutes of this is worth more than any amount of tuning, and it is the step nobody does unless they decide to.

Who this is for

• Long-running relationships with a codebase. Where the value comes from an agent that accumulates understanding rather than starting fresh daily.
• Python environments. Where the harness being Python makes extension and embedding natural.
• Teams that want definitions in files. Profiles, skills, and graphs under version control, reviewed like code.
• Mixed coding and non-coding work. The tool surface extends into documents, databases, and web access.

If your work needs demonstrable governance, identity-bound approvals, and delivered audit, I would point you at Loro instead. These are genuinely different products and I built both rather than compromising between them.

Limits and honest caveats

• Memory needs curation. A graph that accumulates everything degrades recall. Explicit promotion is the mechanism, and someone has to use it.
• Memory is a data store. Whatever the agent learned is written down, including anything sensitive it encountered. Treat the repository accordingly.
• Pre-1.0 surfaces move. The project is approaching 1.0 and some integration surfaces are still stabilizing. The roadmap says which.
• Shell access is the boundary question. As with any capable harness, running commands means the agent can do what you can, unless sandboxed.
• Breadth has a cost. A large tool surface makes tool selection matter. Scope per profile.
• Language servers need a working project setup. The symbol tooling is only as good as the project configuration underneath.

What it is not

MagAgent is not a broker. It runs agents. Deciding which of several installed harnesses should handle a request is a different job, which is what Merced AI does.

MagAgent is not a model provider. It works against several and supplies none.

MagAgent is not a hosted service. It runs on your machine, which means both the operational responsibility and the privacy properties are yours.