devmcp-context: A Simple AI Memory Layer for Your Agent

AI assistants are useful, but they often forget important details between sessions. That makes it hard to keep track of decisions, project notes, bugs, and tasks.

devmcp-context solves that by giving your agent a simple memory layer that lives in your project folder. It is built as a Model Context Protocol (MCP) server, so once you connect it to an agent, the agent can use the MCP tools automatically when it needs to save, read, search, edit, or delete memory.

This post is a quick, easy overview of what it does, how it works, and how you can try it.

Why I Built It

When working with AI tools, I kept running into the same problem:

• The agent would forget previous decisions.
• Important context would get buried in chat history.
• I needed a way to edit memory manually when something changed.
• I wanted a solution that was visible, simple, and file-based.

So I built devmcp-context as a lightweight memory system for AI agents.

What It Does

devmcp-context stores memory in plain text files inside an ai-context/ folder.

That means:

• You can see what the agent remembers.
• You can edit memory directly.
• You can change or delete entries directly from the project folder.
• You can search across saved context.
• You do not need a database.
• The memory survives across sessions.

Memory Categories

The project organizes memory into five categories:

• project for long-term project notes and conventions
• decisions for architecture choices and reasoning
• errors for bugs, failures, and fixes
• tasks for work in progress
• ephemeral for short-lived scratchpad notes

Each category helps keep the memory easy to understand instead of turning into one giant text dump.

How It Works

You do not normally tell the agent to remember every single thing by hand.

Instead, you connect devmcp-context as an MCP server in your agent setup, and then the agent can call the tools when needed:

• context_save to create or update memory
• context_load to read memory from a category
• context_search to find matching entries
• context_delete to remove an entry
• context_status to see category summaries
• context_purge_expired to clean up expired entries

That is the main idea: the agent uses the MCP tools, and the memory stays stored in your project folder where you can inspect it anytime.

How It Looks

The memory is stored as markdown files, so it is easy to inspect and edit.

How to Use It

First, install the package:

pip install devmcp-context

If you use uv:

uv add devmcp-context

After that, connect the server in your agent's MCP config. Once it is connected, the agent can use the tools automatically when it needs them.

Example Workflow

Here is the simple idea:

1. You connect devmcp-context to your agent.
2. The agent uses the MCP tools automatically when it needs to save, read, search, edit, or delete memory.
3. The memory is stored in plain markdown files inside your project folder.
4. If you want, you can still open those files and edit them manually yourself.

That gives you both automation and manual control.

Why This Is Useful

This setup is helpful when you want:

• Better continuity across sessions
• Less repetition in agent conversations
• Clear project memory you can audit
• A simple workflow that fits into Git-based projects

For me, the biggest win is that memory is no longer a black box.

Small Demo

In a real setup, the agent calls the MCP tools through the server, and you still keep full control of the files in the project folder.

context_save(category="decisions", key="auth-strategy", value="Use JWT with refresh tokens", tags=["security"])
context_load(category="decisions")
context_search(query="JWT")

Final Thoughts

devmcp-context is meant to be simple:

• file-based
• human-readable
• searchable
• editable
• persistent

That is what makes it useful: the agent can use the MCP tools automatically, but the memory still lives in plain files you can open, edit, or delete whenever you want.

If you are building AI-assisted workflows and want memory you can trust, this is a good place to start.

If you want to try it, check out the project docs and give it a spin.

Links

• GitHub: github.com/kushal1o1/devmcp-context
• PyPI: pypi.org/project/devmcp-context
• Docs: kushal1o1.github.io/devmcp-context

Comments

[Vadym Arnaut]

File-based markdown memory is the right call for the agent-loop scale. We run something similar for Claude Code sessions: a MEMORY.md index
file plus per-topic .md files split by type (user, feedback, project, reference). The agent loads the index every turn and pulls topic files
on demand.

What we hit:

• The index file gets loaded every turn so it has to stay short. Ours truncates past 200 lines, so we keep the actual index under 150. Worth designing for early.
• Concurrent edits across parallel agent sessions race on the same file. Plain markdown has no merge story. The pragmatic answer was treating the directory as append-mostly and serializing writes through one process.

Five categories is a clean shape but the boundary between decisions and errors gets fuzzy in practice. Does your design nudge the agent
toward one category over the other, or is it free choice?

[Kushal Baral]

yeah v0.1.2 solo open-source lol : )
no hard category rules, agent decides freely but we can guide via prompts if needed. keeping it flexible for now, can tighten later if scaling hits.

thanks for the suggestion ,really helpful

[Harjot Singh]

i totally get the frustration with ai forgetting important details. having a simple memory layer like devmcp-context sounds super useful for keeping track of everything. at moonshift, we have a platform that lets you deploy a full next.js + postgres + auth app in about 7 minutes. if you're interested, i can set up a free run for you to check it out.

[Heinrich Neb]

Congrats on shipping this - and on the instinct that memory must be visible. Plain files you can open and edit is the right first call; everything opaque rots. Three things we only learned after running a memory system in production for months, offered in the spirit of "wish someone had told us":

1. The save path is easy; the recall path is the product. The uncomfortable paradox: the agent that needs a memory doesn't know it's forgotten something - so it never thinks to call context_search. Tool-triggered recall depends on the model noticing its own amnesia, which is exactly what amnesia prevents. Usage changed for us the day relevant memory started arriving at task start without being asked for, with the tools kept for deliberate lookups.

2. Whatever surface lists your memories will truncate them - put the key fact first. We once watched a mistake happen while the note that would have prevented it was on screen - the deciding fact just sat too deep in the entry. Since then: the one number, path, or command leads; backstory follows. A memory that buries its point is a diary entry wearing a database's clothes.

3. On Vadym's decisions-vs-errors boundary - consider typing by outcome, not topic. Give every entry "what worked" and "what failed" as fields, whatever category it lives in. The fuzzy boundary stops mattering: a decision that went wrong IS an error record, and the failure field is the part future sessions need. Related: entries outlive their truth - we caught one of our own memories confidently carrying a stale number just this week. A "superseded by X" marker beats deletion: history stays, recall redirects.

Question that decides more than any other design choice: does anything load memory unprompted at session start, or does recall always wait for the agent to call context_load? If the latter, I'd be genuinely curious how often the tools fire in real sessions - that number surprised us a lot.

[Kushal Baral]

Honestly, this is exactly the kind of feedback I was hoping the project would attract :) .

You’re right that saving is the easy part; recall is where the interesting problem starts. Right now, DevMCP is primarily tool-driven, so the agent has to decide when to call context_search / context_load. I hadn’t fully treated “automatic recall at task start” as a separate product problem yet, but your explanation makes the amnesia paradox very clear.

The “key fact first” point is also a great catch. If the memory surface truncates entries, ordering becomes part of the memory design itself.

And I really like the what_worked / what_failed approach. It feels more useful than forcing a hard decisions-vs-errors boundary, especially once memories become historical and can go stale.

The superseded_by idea is probably something I’ll experiment with too. Deleting stale memories loses useful history, while keeping them without validity information can cause the agent to confidently use outdated information.

For the question one : today recall waits for the agent to call the tools. I don't have enough real-world usage data yet to give you a meaningful tool-fire rate, but that’s definitely a metric worth tracking.

Thanks for the production lessons :) especially the recall point. That’s probably the biggest design question I need to explore with.

[Heinrich Neb]

One starter metric that costs nothing and answers your biggest question: log a single boolean per session - did any recall fire before the first edit? No rates, no dashboards; after two weeks you'll know whether "the agent decides when to call" means "the agent calls" or "the agent forgets." That one bit decides whether automatic recall at task start is a nice-to-have or the product. And on superseded_by: keep the corpse, point it at the successor, and make recall FOLLOW the pointer - returning the successor while mentioning the history. Deleting loses the story; keeping without the pointer serves stale data with confidence. The pointer is the whole feature.

[Kushal Baral]

got it :)