Memory Sidecar is an external long-term memory system that runs alongside an AI agent without modifying the agent itself. It reads the agent's data directory, archives sessions into durable stores, builds long-term knowledge, and injects relevant recall back into future turns. It targets long-running agents whose context spans many sessions, projects, and knowledge sources, where a single prompt-local memory file is not enough.
The sidecar runs an operational loop: read state and session data from AGENT_HOME, archive new sessions into gbrain and a session search index, rebuild governance and curated-knowledge indexes, generate tiered recall context for the next agent turn, and run health and acceptance checks so failures stay visible. Recall is layered across hot, warm, cold, and curated knowledge notes, and fused retrieval combines FTS5 session search, Hindsight facts, gbrain results, and indexed markdown notes.
Compatibility rests on stable data boundaries rather than agent-specific hooks: a writable agent home directory, a state.db, readable session files, and the ability to run Python helper scripts outside the agent process. Supported setups include Hermes Agent, Claude Code, Codex-style local agents, and Cursor-style shared data directories. Requirements are Python 3.9+, PostgreSQL 16, and running Hindsight and gbrain instances.
The installer deploys 28 runtime, support, and observability scripts into $AGENT_HOME/scripts/, offers three dependency-assistance modes from automatic bootstrap to detection-only, and provides bilingual (English and Chinese) output. Semantic recall is optional and driven by a selectable embedding model; without embeddings, text retrieval still works through FTS5, Hindsight, gbrain keyword search, and note indexing.
Features
- Session archiving: sessiontogbrain.py and archive_sessions.py move session output into gbrain and a searchable index
- Tiered recall: tieredcontextinjector.py assembles hot, warm, cold, and curated-knowledge context for the next turn
- Knowledge notes: markdown notes under $AGENT_HOME/knowledge/notes are indexed into a dedicated recall layer
- Health and acceptance checks: memoryguardian.py, sidecaracceptancecheck.py, and runtimedrift_check.py emit machine-readable artifacts
- Alerts: a local webhook receiver forwards action-needed alerts to generic webhooks, Slack, Feishu/Lark, DingTalk, or Telegram with language-adaptive text and dead-letter replay
- Observability: static HTML dashboard, a token-gated server with /api/status JSON and /metrics OpenMetrics, SLO rollups, and Grafana dashboards with a Prometheus/Grafana stack template
- Embedding selection: interactive or --embedding choice among models such as intfloat/multilingual-e5-small, BAAI/bge-m3, and sentence-transformers/LaBSE
- Evaluation registries: synthetic and private memory evaluation registries with five quality metrics and trend comparison
- Install modes: automatic bootstrap, guided step-by-step, or detection-only, with installer rollback tests
- KMM pairing: the Knowledge-and-Memory-Management project supplies curated notes upstream; the sidecar turns them into recallable context
Runs in
Claude Code
Terminal-based agentic coding tool that reads your codebase and runs tasks through natural-language commands
Codex
Lightweight coding agent that runs in your terminal
Hermes
Self-improving AI agent with a learning loop that creates and refines skills, recalls past sessions, and runs across chat platforms
