{"id":50718197,"url":"https://github.com/mage0535/hermes-memory-installer","last_synced_at":"2026-06-13T17:00:41.075Z","repository":{"id":356049741,"uuid":"1220642396","full_name":"mage0535/hermes-memory-installer","owner":"mage0535","description":"Agent-agnostic memory sidecar for AI coding agents. One install, multi-agent shared recall, production-grade. AI智能体持久记忆系统，多Agent共享记忆层，生产级部署。","archived":false,"fork":false,"pushed_at":"2026-06-02T08:53:43.000Z","size":397,"stargazers_count":111,"open_issues_count":1,"forks_count":8,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T09:22:53.449Z","etag":null,"topics":["agent-agnostic","agent-memory","ai-agent","ai-infrastructure","ai-memory","bilingual","claude-code","coding-agent","gbrain","hermes-agent","hindsight","knowledge-graph","llm-memory","memory-sidecar","multi-agent","open-source","persistent-memory","rag","semantic-search","sidecar"],"latest_commit_sha":null,"homepage":"https://github.com/mage0535/hermes-memory-installer","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mage0535.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-25T06:19:46.000Z","updated_at":"2026-06-02T08:53:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mage0535/hermes-memory-installer","commit_stats":null,"previous_names":["mage0535/hermes-memory-installer"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/mage0535/hermes-memory-installer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mage0535%2Fhermes-memory-installer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mage0535%2Fhermes-memory-installer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mage0535%2Fhermes-memory-installer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mage0535%2Fhermes-memory-installer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mage0535","download_url":"https://codeload.github.com/mage0535/hermes-memory-installer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mage0535%2Fhermes-memory-installer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34292326,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-agnostic","agent-memory","ai-agent","ai-infrastructure","ai-memory","bilingual","claude-code","coding-agent","gbrain","hermes-agent","hindsight","knowledge-graph","llm-memory","memory-sidecar","multi-agent","open-source","persistent-memory","rag","semantic-search","sidecar"],"created_at":"2026-06-09T21:00:25.963Z","updated_at":"2026-06-13T17:00:41.068Z","avatar_url":"https://github.com/mage0535.png","language":"Python","funding_links":[],"categories":["*Ops for AI","Deployment and Operations"],"sub_categories":["Model Serving \u0026 Inference","Plugins and add-ons"],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Memory Sidecar v3.1.1\n\n**A production memory system for any AI agent. Keep knowledge across sessions, without touching agent internals.**\n\n[![Version](https://img.shields.io/badge/version-3.1.1-blue?style=flat-square)](https://github.com/mage0535/hermes-memory-installer/releases)\n[![Stars](https://img.shields.io/github/stars/mage0535/hermes-memory-installer?style=flat-square\u0026logo=github\u0026label=stars)](https://github.com/mage0535/hermes-memory-installer/stargazers)\n[![Python](https://img.shields.io/badge/python-3.9+-blue?style=flat-square\u0026logo=python\u0026logoColor=white)](https://www.python.org/)\n[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)\n\n[**中文文档**](README_CN.md) | [**Architecture**](ARCHITECTURE.md)\n\n\u003c/div\u003e\n\n---\n\n## What This Is\n\nAI agents forget things. Every new session starts blank.\n\nMemory Sidecar runs alongside your agent — Hermes, Claude Code, Cursor, Codex, whatever — and gives it a real memory. It saves important conversations, builds long-term knowledge, and feeds relevant context back when needed.\n\nIt doesn't patch the agent. It's a sidecar: separate process, shared data directory.\n\n**Three things it actually does:**\n\n1. **Archives sessions to permanent knowledge** — conversations aren't lost when you restart\n2. **Recalls what matters** — layered retrieval: recent context → semantic search → knowledge graph\n3. **Tracks important topics** — people, projects, recurring problems get their own \"dossier\"\n\n## Architecture at a Glance\n\n```\nAgent writes sessions → state.db + session files\n              ↓\nSidecar reads checkpoint, processes new sessions\n              ↓\n  ┌───────────┼───────────┐\n  │           │           │\n  ▼           ▼           ▼\nHot Layer   Warm Layer  Cold Layer\n(memory     (Hindsight  (gbrain graph\n tool,      PostgreSQL)  + FTS5 search)\n 5KB cap)               \n              ↓\n  Tiered context injection → agent's system prompt\n```\n\nThe full stack is documented in [ARCHITECTURE.md](ARCHITECTURE.md). Short version:\n\n| Layer | What | Technology | Speed |\n|-------|------|-----------|-------|\n| Hot | Current user + system facts | memory tool injection | 0ms |\n| Warm | Extracted facts, recurring patterns | Hindsight (PostgreSQL 16) | ~50ms |\n| Cold | Permanent archive, knowledge graph | gbrain + FTS5 session search | ~500ms–2s |\n\nWe dropped the intermediate agentmemory bridge layer from earlier versions. It added Docker overhead with barely any data. The current three layers are simpler, faster, and more reliable.\n\n## Quick Start\n\n### What you need\n\n- Python 3.9+\n- [gbrain](https://github.com/hi-ogawa/gbrain) (knowledge graph, running on port 8787)\n- [Hindsight](https://github.com/HindsightTechnologySolutions/hindsight) (fact store, port 8890)\n- PostgreSQL 16 (backing store for both of the above)\n- An AI agent producing sessions (Hermes, Claude Code, etc.)\n\n### Install\n\n```bash\ngit clone https://github.com/mage0535/hermes-memory-installer.git\ncd hermes-memory-installer\n\n# Set AGENT_HOME to point to your agent's data directory\nexport AGENT_HOME=\"$HOME/.hermes\"   # or ~/.claude, ~/.cursor, etc.\n./install.sh\n```\n\nThe installer will:\n\n1. **Check your environment** — Python, PostgreSQL, Hindsight, gbrain reachability\n2. **Let you pick an embedding model** — for semantic search (optional but recommended)\n3. **Deploy sidecar scripts** — to `$AGENT_HOME/scripts/`\n4. **Patch agent config** — adds memory provider settings if a config file is found\n\nNon-interactive mode:\n\n```bash\n./install.sh --noninteractive --agent-home \"$HOME/.my-agent\"\n```\n\n### After Installing\n\n```bash\n# Run one archive pass\npython3 $AGENT_HOME/scripts/session_to_gbrain.py --resume\n\n# Run the full maintenance cycle\npython3 $AGENT_HOME/scripts/memory_maintenance_cycle.py\n\n# Verify everything works\npython3 $AGENT_HOME/scripts/sidecar_acceptance_check.py\n```\n\nFor ongoing operation, schedule the maintenance cycle via cron (or your agent's built-in scheduler). See [ARCHITECTURE.md](ARCHITECTURE.md) for recommended schedules.\n\n## The Scripts\n\nSeven scripts run the sidecar. All live in `$AGENT_HOME/scripts/` after install:\n\n| Script | Role |\n|--------|------|\n| `session_to_gbrain.py` | Incremental session → gbrain archive with MCP API bridge |\n| `memory_governance_rebuild.py` | Rebuild session index, hubs, canonical objects, vector index |\n| `memory_guardian.py` | Capacity monitoring, backlog detection, stuck operation recovery |\n| `memory_family_registry.py` | Query intent classification + Focused Dossier routing |\n| `tiered_context_injector.py` | Layered recall: Hot → Warm → Cold → RRF fusion |\n| `memory_maintenance_cycle.py` | Orchestrator: archive → rebuild → drain → recall → health |\n| `sidecar_acceptance_check.py` | Production validation suite |\n| `archive_sessions.py` | Bulk session archival to gbrain (in cron at 2am) |\n| `auto_session_summary.py` | Session digest generation, runs every 6 hours |\n\n**Running in production (cron):** `session_to_gbrain.py`, `archive_sessions.py`, `auto_session_summary.py`\n\n**Available on-demand:** `memory_governance_rebuild.py`, `memory_guardian.py`, `memory_family_registry.py`, `tiered_context_injector.py`, `memory_maintenance_cycle.py`, `sidecar_acceptance_check.py`\n\n\n## Focused Dossiers\n\nSome things matter more than others. A key person. A long-running project. A recurring incident.\n\nv3.1.0 lets you declare **Focused Dossiers** — high-priority memory profiles that get special treatment in recall. A dossier has:\n\n- **aliases** — all the names it's referred to by\n- **topic markers** — keywords that trigger dossier-first retrieval\n- **retention priority** — don't let this get pruned\n- **timeline tracking** — chronological entries for major events\n\nThe first production dossier is `kiki` — a relationship memory profile that demonstrated the pattern works at scale (hundreds of sessions, thousands of extracted facts, timeline-aware recall).\n\nTo add your own, edit `memory_family_registry.py` and add a new profile entry. The format is self-documenting in the file.\n\n## Embedding Model Selection\n\nSemantic search needs embeddings. The sidecar supports pluggable models via sentence-transformers.\n\nDuring install, you pick one. The installer records your choice but doesn't deploy the model — you run the embedding service separately.\n\n**How it affects retrieval:**\n- Semantic matching catches meaning, not just keywords\n- Cross-lingual: Chinese queries find English content\n- Better clustering of related facts even when wording differs\n\n**Supported models:**\n\n| Model | Langs | Dim | Size | Best For |\n|---|---|---|---|---|\n| `intfloat/multilingual-e5-small` ★ | 100+ | 384d | ~470MB | Default. Balanced multilingual |\n| `BAAI/bge-small-zh-v1.5` | Chinese | 512d | ~96MB | Tiny Chinese-first deployment |\n| `paraphrase-multilingual-MiniLM-L12-v2` | 50+ | 384d | ~471MB | Mature ST ecosystem |\n| `Alibaba-NLP/gte-multilingual-base` | 75+ | 768d | ~610MB | Higher recall, more RAM |\n| `sentence-transformers/LaBSE` | 109 | 768d | ~471MB | Strong cross-lingual alignment |\n| `BAAI/bge-m3` | 100+ | 1024d | ~2GB | Maximum precision, needs resources |\n\n### Deploying the Embedding Service\n\n```bash\npip install sentence-transformers flask\n```\n\nMinimal server:\n\n```python\nfrom sentence_transformers import SentenceTransformer\nfrom http.server import HTTPServer, BaseHTTPRequestHandler\nimport json\n\nmodel = SentenceTransformer(\"intfloat/multilingual-e5-small\")\n\nclass Handler(BaseHTTPRequestHandler):\n    def do_POST(self):\n        length = int(self.headers.get(\"Content-Length\", 0))\n        body = json.loads(self.rfile.read(length))\n        texts = body.get(\"input\", [])\n        emb = model.encode(texts, normalize_embeddings=True).tolist()\n        self.send_response(200)\n        self.send_header(\"Content-Type\", \"application/json\")\n        self.end_headers()\n        self.wfile.write(json.dumps(\n            {\"data\": [{\"embedding\": e} for e in emb]}\n        ).encode())\n\nHTTPServer((\"127.0.0.1\", 8766), Handler).serve_forever()\n```\n\nSet the URL and rebuild governance:\n\n```bash\nexport EMBEDDING_API_URL=http://127.0.0.1:8766/v1/embeddings\npython3 $AGENT_HOME/scripts/memory_maintenance_cycle.py\n```\n\nNo embedding service? No problem — text-based retrieval (FTS5, LIKE, Hindsight, gbrain) works without it.\n\n## Works With Any Agent\n\nMemory Sidecar is agent-agnostic. It reads from `$AGENT_HOME/state.db` and session files, and operates entirely outside the agent process.\n\nTested with:\n- **Hermes Agent** — original companion, 2+ months production\n- **Claude Code** — via `AGENT_HOME=~/.claude`\n- **Cursor / Codex** — shared data directory pattern\n\nThe installer respects `AGENT_HOME` (falls back to `HERMES_HOME` for backward compatibility). If your agent stores data somewhere non-standard, point `--agent-home` at it.\n\n## Production Track Record\n\nThis isn't a prototype. The current stack has been running continuously on a production Hermes installation since April 2026:\n\n- **10,885 gbrain pages** — full knowledge graph with timeline tracking\n- **42,481 Hindsight nodes** — extracted facts with auto-retain/recall/reflect\n- **105,601 indexed messages** — FTS5 searchable session archive\n- **100% embedding coverage** — vector search across all content\n- **brain score 73** — gbrain content quality metric\n\n## Changelog\n\n### v3.1.1 (2026-06-08)\n\n- **New scripts**: `memory_watermark.py` (auto-detect memory capacity and archive stale entries) + `memory_snapshot_backup.py` (periodic snapshot backup)\n- **Updated**: `hindsight-service.py` — simplified standalone daemon using existing PG on port 5432\n- **Updated**: `hindsight_mcp_bridge.py` — clean line endings and improved MCP stdio bridge\n- **Updated**: `session_to_gbrain.py` — env-var-based token config (no more hardcoded secrets)\n- **Docs**: repo layout now reflects 9 scripts instead of 7\n\n### v3.1.0 (2026-06-02)\n\n- Simplified 4-tier → 3-tier architecture (removed agentmemory Docker bridge)\n- Removed `memory_index.db` (semi-finished layer)\n- Agent-agnostic via `AGENT_HOME` (not hardcoded to Hermes)\n- Interactive embedding model selection during install\n- Dry-run mode (`--dry-run`)\n- Bilingual README (EN/CN) with language switching\n- ARCHITECTURE_CN.md — Chinese architecture translation\n- Focused Dossier model (first production instance: Kiki)\n- Embedding Model selection guide (6 models)\n- Production track record: 10.8K pages, 42K nodes, 100% embed coverage\n\n### v3.0.0 (2026-05-29)\n\n- Complete documentation overhaul\n- Added HERMES_AUDIT_REPORT.md — comprehensive agent capability audit\n- Optimized Chinese README for SoV/SEO\n- 4-tier architecture: Hot → Warm → Cold → Archive\n\n## Repository Layout\n\n```\ninstaller/     Entry point, config patching, environment checks\n|scripts/       9 supported sidecar scripts (incl. memory_watermark, memory_snapshot_backup)\n|skills/        Agent-side memory skills (starter-kit, proactive, archivist)\ntemplates/     Memory templates\n```\n\n## Acknowledgements\n\n### Core Projects\n\n- [Hermes Agent](https://github.com/NousResearch/hermes-agent) — the agent this sidecar was built alongside\n- [Hindsight](https://github.com/HindsightTechnologySolutions/hindsight) — short/medium-term fact graph\n- [gbrain](https://github.com/hi-ogawa/gbrain) — personal knowledge graph engine\n- [sentence-transformers](https://www.sbert.net/) — embedding model framework\n- [PostgreSQL](https://www.postgresql.org/) + [pgvector](https://github.com/pgvector/pgvector) — vector storage backbone\n- [OpenCode](https://opencode.ai) — guided architecture and production iteration\n\n### Embedding Models\n\n- [intfloat/multilingual-e5-small](https://huggingface.co/intfloat/multilingual-e5-small)\n- [BAAI/bge-small-zh-v1.5](https://huggingface.co/BAAI/bge-small-zh-v1.5)\n- [sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2](https://huggingface.co/sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2)\n- [Alibaba-NLP/gte-multilingual-base](https://huggingface.co/Alibaba-NLP/gte-multilingual-base)\n- [sentence-transformers/LaBSE](https://huggingface.co/sentence-transformers/LaBSE)\n- [BAAI/bge-m3](https://huggingface.co/BAAI/bge-m3)\n\n### Community\n\nShoutout to everyone who filed issues, surfaced recall gaps, and pushed the design forward. GitHub Issues, Discussions, Reddit (r/LocalLLaMA, r/MachineLearning), V2EX, and direct production feedback all shaped v3.1.0.\n\n---\n\nIf this project helps you, [drop a star ⭐](https://github.com/mage0535/hermes-memory-installer) — it helps others find it too.\n\n## License\n\nMIT. See bundled dependencies for their respective licenses.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmage0535%2Fhermes-memory-installer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmage0535%2Fhermes-memory-installer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmage0535%2Fhermes-memory-installer/lists"}