DEV Community

mage0535
mage0535

Posted on

Give Your AI Agent a Real Memory: The Sidecar Approach

#ai #memory #opensource

If you've ever used Claude Code, Cursor, Codex, or Hermes for more than a single session, you've probably run into the same frustration: each new conversation starts from scratch. The agent has no idea what you worked on yesterday, last week, or even an hour ago. Sure, you can paste context, but that manual step scales poorly. Some tools offer limited memory patches, but they're agent-specific, invasive, and often break on updates.

That's why I built Memory Sidecar — a publishable, agent-agnostic memory system that runs next to your agent without patching a single line of its code. It sits in your $AGENT_HOME directory, reads the agent's data, archives sessions, builds long-term knowledge, and injects relevant recall back into future work. It's been in production use for months, and version 3.5.1 is an operational hardening release that focuses on stability and reliability.

How It Works

The architecture is deliberately non-invasive. The sidecar monitors the agent's data directory for new sessions, extracts conversations and key decisions, chunk them into knowledge units, and stores them in an embedded vector index. When you start a new task, it retrieves the most relevant past context and injects it into the agent's prompt — all without asking for your input.

Here's the high-level flow:

  1. Monitor – A lightweight daemon watches for new chat logs, session exports, or tool outputs.
  2. Process – Each session is parsed into structured chunks (code snippets, design decisions, error fixes).
  3. Index – The chunks are embedded and stored using a local vector database (FAISS or Chroma, configurable).
  4. Retrieve – When a new task begins, the sidecar identifies similar past sessions and appends their key context as a system message.

What v3.5.1 Brings

The public release v3.5.0 made the project installable via a single script. Version 3.5.1 is the hardening release that focused on:

  • Canonical runtime path resolution – No more "file not found" errors after directory changes.
  • Evaluation trend comparison – Track how your agent's recall quality improves over time.
  • Private registry linting – Ensures custom knowledge sources are well-formed.
  • Policy validity/conflict metadata – Catch misconfigured exclusion rules before they break retrieval.
  • Dry-run gbrain edge planning – Preview scheduling decisions before the sidecar acts.

All of this means the sidecar is ready for daily, unattended operation. The cron job for memory quality is registered in a paused state by default; you unpause it after reviewing your own pipeline.

Using It With Your Agent

Memory Sidecar is completely agent-agnostic. You can use it with Hermes, Claude Code, Codex, Cursor, or any agent that writes session data to a directory. The installer sets up $AGENT_HOME/memory-sidecar with all required modules, scripts, and documentation. From there:

# Install the sidecar into your agent environment
./install.sh --agent-home $AGENT_HOME

# Start the memory daemon
systemctl --user start memory-sidecar

# Manually trigger a recall injection for testing
python3 $AGENT_HOME/memory-sidecar/recall.py --inject
Enter fullscreen mode Exit fullscreen mode

The sidecar's output is a JSON payload that your agent can incorporate into its system prompt. Most of the supported agents can read this natively via environment variables or init hooks.

When It Works (and When It Doesn't)

This approach shines for:

  • Long-running projects – The same codebase, multiple sessions over days or weeks.
  • Personal assistants – An agent that learns your preferences, stack, and common errors.
  • Team knowledge bases – Shared cache of resolved issues and decisions.

It's not a fit for:

  • Purely ephemeral agents – If you never need past context, this is overhead.
  • Heavily sandboxed environments – If the agent can't read a sidecar output file, injection fails.
  • Real-time collaboration – The sidecar is optimized for session-level recall, not streaming.

Why Open Source?

Agent memory shouldn't be a vendor lock-in. The sidecar is MIT licensed, and the whole stack is a few thousand lines of Python. You can audit every step, add your own embedding model, or swap the vector store. No telemetry, no accounts, no cloud dependency.

If you've been struggling with agent amnesia, give the sidecar a try. The GitHub repo includes a full architecture document and a quick-start guide. It's already running in production for several teams, and the 3.5.1 release makes it rock solid.

GitHub: github.com/mage0535/hermes-memory-installer – Releases, documentation, and community discussions.

Top comments (0)