Memory Sidecar v3.5.2

v3.5.2 adds privacy-safe synthetic and private memory evaluation registries, five quality metrics, additive governance policy metadata, and dry-run-first gbrain edge planning. See the v3.5.2 release notes.

The follow-up memory quality optimization adds canonical runtime path resolution, evaluation trend comparison, private registry linting, policy validity/conflict metadata, gbrain plan summaries, and an operator report. See the optimization report.

In production, runtime scripts execute from $AGENT_HOME/scripts. The sibling $AGENT_HOME/memory-sidecar directory supplies additive Python modules, docs, and installer assets. The memory-quality cron block is registered in a paused remediation state by default and is explicitly unpaused only after operational review.

A publishable, agent-agnostic memory sidecar for Hermes, Claude Code, Codex, Cursor, and similar agents.

中文说明 | Architecture

What This Is

Memory Sidecar is an external memory system that runs next to an AI agent without patching the agent itself. It reads the agent's data directory, archives sessions, builds long-term knowledge, and injects relevant recall back into future work.

Release 3.5.1 is the operational hardening release for the current public architecture:

• agent-agnostic install flow driven by AGENT_HOME
• layered recall across hot, warm, cold, and curated knowledge notes
• clean public repository with no server-specific paths or credentials
• install surface aligned with the actual deployed script set

This repository is suitable for public install feedback from technical users running their own Hindsight + gbrain + PostgreSQL environment.

Why It Was Built

Long-running AI agents tend to lose useful context when work spans many sessions, projects, and knowledge sources. A single prompt-local memory file is not enough for durable recall, and operators need to know when archival, recall, or compaction silently stops working.

Memory Sidecar was built to make memory an installable, observable sidecar rather than a hidden agent-core modification.

Design Goals

• Keep the agent core untouched.
• Use stable data boundaries such as AGENT_HOME, state.db, sessions, Hindsight, gbrain, and markdown notes.
• Combine hot, warm, cold, and curated knowledge recall.
• Emit machine-readable health artifacts for automation.
• Keep the public repository free of private server paths, credentials, and production data.

How It Works

The sidecar follows a simple operational loop:

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. Generate tiered recall context for the next agent turn
5. Run health checks and acceptance checks so failures stay visible

What It Improves

The sidecar is designed to improve memory in three concrete ways:

1. It archives session output into durable stores instead of letting history disappear with a single conversation window.
2. It retrieves context from multiple layers instead of relying on one prompt-local memory file.
3. It lets curated knowledge notes participate in recall, so project playbooks and wiki pages can influence future answers.

Public Release Scope

v3.5.1 intentionally separates the generic sidecar from host-specific operations:

• Installed by default: the generic multi-agent sidecar runtime, installer, CLI, and memory skills.
• In this repository but not installed by default: memory_watermark.py and memory_snapshot_backup.py.

Those two operational helpers are Hermes-oriented maintenance scripts with stronger host assumptions, so they are not installed by default in the public multi-agent path.

Requirements

• Python 3.9+
• PostgreSQL 16
• Hindsight running and reachable
• gbrain running and reachable
• An agent data directory containing state.db and session files

Supported examples:

• Hermes Agent
• Claude Code
• Codex / Codex-style local agents
• Cursor-style shared data directory setups

Quick Start

git clone https://github.com/mage0535/hermes-memory-installer.git
cd hermes-memory-installer

export AGENT_HOME="$HOME/.hermes"   # or ~/.claude, ~/.cursor, ~/.agent, etc.
./install.sh

Non-interactive mode:

./install.sh --noninteractive --agent-home "$HOME/.my-agent"

Install Modes

The installer supports three install modes for dependency assistance:

• --install-mode 3 Default. Tries the most automatic dependency bootstrap path first.
• --install-mode 2 Guided dependency assistance. Shows the recommended commands and lets you continue step by step.
• --install-mode 1 Detection-only mode. Does not change the system and prints what is missing.

If mode 3 fails, re-run with:

./install.sh --install-mode 2

If mode 2 still does not work, fall back to:

./install.sh --install-mode 1

The installer also supports bilingual output:

./install.sh --lang en
./install.sh --lang zh

When --lang is omitted, the installer falls back to locale detection.

After install:

python3 "$AGENT_HOME/scripts/session_to_gbrain.py" --resume
python3 "$AGENT_HOME/scripts/memory_maintenance_cycle.py"
python3 "$AGENT_HOME/scripts/sidecar_acceptance_check.py"

Installed Script Set

The public installer deploys 28 runtime, support, and observability scripts into $AGENT_HOME/scripts/.

Entry scripts:

• session_to_gbrain.py
• memory_governance_rebuild.py
• memory_guardian.py
• memory_family_registry.py
• tiered_context_injector.py
• memory_maintenance_cycle.py
• sidecar_acceptance_check.py
• archive_sessions.py
• auto_session_summary.py
• gbrain_deorphan_index.py
• memory_observability_report.py
• memory_storage_cross_check.py
• runtime_drift_check.py
• gbrain_stale_maintenance.py
• alert_queue.py
• alert_webhook_receiver.py
• metrics_dashboard.py
• metrics_dashboard_server.py
• openmetrics_exporter.py
• slo_rollup.py
• profile_isolation_soak.py
• synthetic_recall_benchmark.py
• hindsight_security_audit.py

Support modules:

• state_db_schema.py
• knowledge_notes.py
• recall_samples.py
• langsmith_monitor.py
• langsmith_task_wrapper.py
• langsmith_trend_report.py

Optional repository-only helpers:

• memory_watermark.py
• memory_snapshot_backup.py

Repository Structure

• installer/ contains the install entrypoint and environment checks
• scripts/ contains the runtime sidecar entry scripts and support modules
• skills/ contains agent-side memory skills
• templates/ contains reusable memory templates
• docs/ contains planning, verification, and release notes

Knowledge Integration

Memory Sidecar can consume curated markdown knowledge in addition to session history.

By default, governance rebuild checks:

• $AGENT_HOME/knowledge/notes
• legacy knowledge layouts such as $AGENT_HOME/knowledge/wiki/wiki

These notes are indexed into a dedicated knowledge recall layer and participate in fused retrieval alongside session search, Hindsight facts, and gbrain results.

Knowledge-and-Memory-Management

For a larger knowledge workflow, pair this project with Knowledge-and-Memory-Management.

That project extends the sidecar with:

• structured knowledge collection pipelines
• wiki and note management
• broader sync and ingestion tooling
• a larger operating model for "where knowledge comes from and how it is maintained"

Practical boundary:

• hermes-memory-installer is the memory sidecar runtime and installer
• Knowledge-and-Memory-Management is the upstream knowledge capture and curation layer

Used together, KMM supplies curated notes and source material, and Memory Sidecar turns that material into recallable context for agents.

Embeddings

Semantic recall is optional but recommended. The installer records the selected model, while the embedding service itself is run separately.

Embedding Model Selection

The installer keeps the interactive embedding model selection flow.

• You can pick from multiple built-in models during install.
• You can still pass a model directly with --embedding.
• In interactive mode, you can choose a custom model id as well.

Recommended default:

• intfloat/multilingual-e5-small

Common alternatives:

• BAAI/bge-small-zh-v1.5: lightweight Chinese-first deployments.
• paraphrase-multilingual-MiniLM-L12-v2: mature sentence-transformers ecosystem.
• Alibaba-NLP/gte-multilingual-base: higher quality when RAM headroom is available.
• sentence-transformers/LaBSE: cross-language alignment.
• BAAI/bge-m3: maximum recall quality with higher resource cost.

Alerts And Dashboard

alert_queue.py normalizes health artifacts into a local queue. alert_webhook_receiver.py provides a real local webhook target, can forward action-needed alerts to generic webhooks, Slack, Feishu/Lark, DingTalk, or Telegram via private environment variables, and can replay dead-letter rows after a downstream outage.

Alert text is language-adaptive:

• payload.lang / payload.preferred_lang / payload.user_lang takes priority
• for Telegram, a cached per-chat language learned from bot updates takes priority over defaults
• otherwise MEMORY_ALERT_LANG, MEMORY_UI_LANG, or system locale is used
• current defaults support zh and en

Telegram note:

• Telegram client language is only learnable after the user has sent at least one message to the bot.
• telegram_language_sync.py reads bot updates, stores chat_id -> lang, and later outbound alerts reuse that language automatically.
• For multi-recipient delivery, start from config/alert_recipients.example.json and place the real file in $AGENT_HOME/private/alert-recipients.json.

metrics_dashboard.py renders a static HTML dashboard. metrics_dashboard_server.py can serve HTML, /api/status JSON, and /metrics OpenMetrics text behind a bearer/query token, and binds to 127.0.0.1 by default. slo_rollup.py summarizes acceptance rate, alert queue growth, dead-letter replay success, and recall latency quantiles into slo-rollup-latest.json. synthetic_recall_benchmark.py provides a private-data-free recall regression fixture for CI.

For shell and monitoring probes:

hermes-memory status
hermes-memory slo-rollup
hermes-memory openmetrics

Grafana dashboards included in the repository:

• docs/grafana/hermes-memory-home.json: operator home page
• docs/grafana/hermes-memory-openmetrics-dashboard.json: detailed OpenMetrics dashboard

A ready-to-run Prometheus/Grafana stack template is included in deploy/observability/README.md.

That stack now also includes:

• prometheus-rules.yml for default alert rules
• provision_dashboards.py to import the dashboards through the Grafana API and set the default Grafana home dashboard

Reverse proxy templates are available in [docs/dashboard-reverse-proxy.md](docs/dashboard-re