DEV Community

mage0535
mage0535

Posted on

End AI Agent Amnesia: A Practical Guide to Persistent Memory with an Open Source Sidecar

#ai #memory #opensource

If you’ve been using coding agents like Claude Code, Codex, or Cursor for more than a single session, you’ve probably felt the frustration: start a new terminal, run a new task, and yesterday’s work is gone. The agent has no recollection of the dependencies you battled, the commit messages you settled on, or the bug you traced for an hour. It’s like Groundhog Day for software development.

I hit this wall hard. I was using Claude Code to manage a microservice monorepo, and every fresh session meant pasting in the same high-level context, re-typing decisions, and hoping the agent didn’t repeat mistakes I’d already fixed. Patching the agent’s internal memory wasn’t practical (and often required deep, fragile hooks). Copy-pasting entire logs or using MCP tools felt like duct tape. I needed something that worked next to the agent, not inside it.

That’s why I built Memory Sidecar – an external, agent-agnostic memory system that sits alongside your AI agent, learns from past sessions, and feeds that knowledge back when it matters most. It’s now live as an open-source project (v3.5.1), and I want to share how it works so you can decide if it fits your workflow.

The Core Idea: Memory Without Agent Hacks

The sidecar treats memory as an external service, not a feature to hack into the agent’s psyche. It reads your agent’s data directory (driven by the AGENT_HOME variable), archives completed sessions, and builds a layered knowledge store. When a new session starts, the sidecar injects relevant recall back into the agent’s context – as a file, a tool definition, or environment variables.

No monkey-patching. No modification of the agent binary. Just a sidecar process that watches and serves.

Layered Recall Architecture

To keep memory both useful and performant, the sidecar organises knowledge into four tiers:

  • Hot – the last few raw sessions, available immediately for near-term context.
  • Warm – summarised patterns extracted from recent sessions (common command line flags, project conventions).
  • Cold – compressed, long-term knowledge from archived sessions (past decision logs, error histories).
  • Curated – user-defined notes that you explicitly pin (API design rules, infrastructure URLs, preferred tools).

During a new session, the sidecar picks the most relevant items from each tier, weights them by recency and similarity to the current task, and compiles them into a “knowledge injection” that the agent can consume as if it were part of the native context.

How to Get It Running (It’s Quick)

The install flow is agent-agnostic. You point it at your agent’s home directory, and it sets itself up:

git clone https://github.com/mage0535/hermes-memory-installer.git
cd hermes-memory-installer
python install.py --agent $(dirname $(which claude))   # for Claude Code
# or substitute the path to your agent’s binary directory
Enter fullscreen mode Exit fullscreen mode

The AGENT_HOME-driven design means it works with Claude Code, Codex, Cursor, Hermes, and any agent that stores sessions in a filesystem. The sidecar doesn’t care what’s on the other side of the pipe – it only cares about the directory structure.

Real-World Impact

Since adding the sidecar to my daily workflow, the biggest change is continuity. I can start a new task, and the agent remembers the load balancer token I set three days ago, the docker-compose.override.yml I created for local testing, and why we decided to use async workers for that one endpoint. It doesn’t waste context window repeating past info – it spends it on what’s new.

Yes, there’s a trade-off: memory injection occasionally includes stale context if you’ve significantly changed course. But the warm and curated tiers let you override that with manual pinning, and the cold tier automatically deprioritises very old sessions after three renewal cycles. For everyday work, the 80% of “good recall” is a massive win over zero recall.

When Should You Not Use This?

  • If your agent already has a robust native memory interface (e.g., you’re fully on a managed service like ChatGPT Pro with personalised memory), this sidecar may overlap.
  • If your project is a single-session throwaway (one-off script, quick prototype), the overhead of setting up memory isn’t worth it.
  • If you’re deeply concerned about privacy in agent session contents, be aware the sidecar reads and stores your agent’s data – though it stores nothing outside the local filesystem, and the code is open for audit.

v3.5.1: Operational Hardening

The latest release is all about making the sidecar boringly reliable for daily use. Cleaner AGENT_HOME detection, no more hardcoded paths, and a simpler install surface. No new shiny features – just the stability that comes from heavy iterative testing with Claude Code and Codex.

Try It Yourself

If you’ve been annoyed by your coding agent’s amnesia, give the sidecar a spin. It’s MIT-licensed, runs on plain Python 3.9+, and takes five minutes to try. Your future self (and your agent) will thank you.

GitHub: github.com/mage0535/hermes-memory-installer

Drop a star or open an issue if you hit something – I’m actively developing based on real feedback.

Top comments (0)