Memory Sidecar: Turn Your AI Agent Into a System That Remembers

AI agents forget. Not because they're lazy — because a single conversation window is a terrible place to keep everything you've ever told them. Run an agent across dozens of sessions, projects, and knowledge sources and the useful context from last week simply isn't there anymore.

This is the problem Memory Sidecar (github.com/mage0535/hermes-memory-installer, 192★, MIT, Python 3.9+) was built to solve. It's an external memory system that runs next to an agent without patching the agent itself — a sidecar, not a surgery.

Why a Sidecar Instead of a Core Patch

There are two ways to give an agent long-term memory:

1. Patch the agent core — invasive, breaks on every upgrade, ties you to one vendor.
2. Run a sidecar — read the agent's data directory, archive sessions, build long-term knowledge, and inject relevant recall back into future work.

The sidecar approach wins on a simple principle: stable data boundaries. It reads AGENT_HOME, state.db, session files, Hindsight facts, gbrain pages, and markdown knowledge notes. It never touches the agent's own code. That means the same memory system works for Hermes, Claude Code, Codex, Cursor, or any agent that keeps its data in a directory.

The Operational Loop

The sidecar follows a five-step cycle:

1. Read the agent's state and session data from AGENT_HOME
2. Archive new sessions into gbrain and the session search index
3. Rebuild governance indexes and curated knowledge note indexes
4. Inject tiered recall context into the next agent turn
5. Verify with health and acceptance checks so failures stay visible

Step 5 is the part most memory systems skip — and the part that matters in production. A memory pipeline that silently stops archiving is worse than no memory at all, because you believe it's working. The sidecar ships 28 runtime scripts including sidecar_acceptance_check.py, runtime_drift_check.py, gbrain_stale_maintenance.py, and alert_queue.py so that memory failures surface as alerts, not surprises.

Layered Recall: Hot, Warm, Cold, and Curated

A single prompt-local memory file isn't enough for durable recall. Memory Sidecar fuses four layers:

Layer	Source	Role
Hot	recent sessions	immediate context
Warm	Hindsight facts	extracted knowledge
Cold	gbrain pages	long-term archive
Curated	markdown knowledge notes	project playbooks & wiki

Curated knowledge is the interesting one. Put a playbook in $AGENT_HOME/knowledge/notes, and it participates in fused retrieval alongside session search, Hindsight facts, and gbrain results. Your project's conventions start influencing every future answer — not just the ones where you remember to paste them into the prompt.

Install in Three Commands

git clone https://github.com/mage0535/hermes-memory-installer.git
cd hermes-memory-installer
export AGENT_HOME="$HOME/.hermes"   # or ~/.claude, ~/.cursor, ~/.agent
./install.sh

The installer is agent-agnostic by design: it's driven entirely by AGENT_HOME, deploys 28 runtime scripts, and supports three dependency-assistance modes (3 automatic, 2 guided, 1 detection-only) plus bilingual output (--lang en|zh).

Requirements: Python 3.9+, PostgreSQL 16, Hindsight and gbrain running and reachable.

What It Actually Improves

Three concrete wins, measured against the "one prompt-local memory file" baseline:

1. Session output is archived into durable stores instead of vanishing with the conversation window. archive_sessions.py + session_to_gbrain.py turn yesterday's work into tomorrow's context.
2. Recall comes from multiple layers instead of one file. If Hindsight misses a fact, gbrain still has the page; if gbrain is stale, the session index still has the transcript.
3. Knowledge notes influence recall. Project playbooks, architecture decisions, and wiki pages become first-class citizens in the retrieval path.

Production Hardening You Can Actually Audit

The current release (v3.5.x) is the operational hardening pass, and it shows in the details:

• Dry-run-first gbrain planning — the installer shows you what it would do before it does it
• Privacy-safe evaluation registries — synthetic and private memory evaluation without leaking data
• Five quality metrics with evaluation trend comparison
• Additive governance policy metadata — policy validity and conflict checks
• Clean public repo — no server-specific paths or credentials in the repository

Two operational helpers (memory_watermark.py, memory_snapshot_backup.py) are intentionally not installed by default — they're Hermes-oriented maintenance scripts with stronger host assumptions. The public path stays generic.

Pair It With Knowledge-and-Memory-Management

For a larger knowledge workflow, pair the sidecar with Knowledge-and-Memory-Management (8★):

• Memory Sidecar = the runtime + installer (turns material into recallable context)
• KMM = the upstream capture layer (structured collection pipelines, wiki management, 40+ ingestion tools)

Together they answer the full question: where does knowledge come from, and how is it maintained?

The Takeaway

Memory isn't a feature you bolt onto a prompt. It's an operational system: collect, archive, index, recall, verify. Memory Sidecar treats it that way — installable, observable, and agent-agnostic. If you run long-lived agents across many sessions, that's exactly the layer you're missing.

---

Written from hands-on maintenance of a production Hermes + Hindsight + gbrain + PostgreSQL environment. MIT-licensed, open for feedback and contributions.