{"id":49306925,"url":"https://github.com/smarzola/hermes-local-memory","last_synced_at":"2026-04-26T10:01:34.401Z","repository":{"id":353746340,"uuid":"1220732691","full_name":"smarzola/hermes-local-memory","owner":"smarzola","description":"Local-first SQLite memory provider for Hermes Agent","archived":false,"fork":false,"pushed_at":"2026-04-25T11:20:51.000Z","size":96,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-25T11:25:40.464Z","etag":null,"topics":["agent-memory","ai-agents","hermes-agent","local-first","sqlite"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smarzola.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-25T08:58:51.000Z","updated_at":"2026-04-25T11:20:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/smarzola/hermes-local-memory","commit_stats":null,"previous_names":["smarzola/hermes-local-memory"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/smarzola/hermes-local-memory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smarzola%2Fhermes-local-memory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smarzola%2Fhermes-local-memory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smarzola%2Fhermes-local-memory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smarzola%2Fhermes-local-memory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smarzola","download_url":"https://codeload.github.com/smarzola/hermes-local-memory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smarzola%2Fhermes-local-memory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32292958,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-memory","ai-agents","hermes-agent","local-first","sqlite"],"created_at":"2026-04-26T10:01:33.559Z","updated_at":"2026-04-26T10:01:34.383Z","avatar_url":"https://github.com/smarzola.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hermes Local Memory\n\n**Local-first, inspectable, agent-controlled memory for Hermes Agent.**\n\nHermes Local Memory is an open-source SQLite memory provider for [Hermes Agent](https://github.com/NousResearch/hermes-agent). It is built for people who want the useful parts of agent memory — profiles, aliases, raw history, facts, cards, search, context injection, migration, and consolidation — without running a separate memory server or trusting an opaque background \"dream\" system.\n\nThe core idea is simple:\n\n\u003e Memory should be a first-class part of the Hermes Agent runtime: a local, auditable substrate that the agent can inspect, reason over, maintain, and update through explicit tools — not an opaque appendix bolted onto the side of the agent.\n\nThis project is inspired by the good ideas in Honcho, especially peers/cards/consolidation, but deliberately chooses boring engineering: one local SQLite DB, explicit identity mapping, deterministic retrieval, source-labeled context, conservative maintenance dry-runs before writes, and agent-generated patches instead of hidden backend mutation.\n\n\u003e Status: **alpha**. The store, provider, plugin shim, CLI inspection/repair tools, Hermes markdown import, Honcho API import, identity maps, peer/candidate/card review, reflection, and deterministic consolidation are implemented and tested. Do not switch a production Hermes setup without doing a trial import and inspection first.\n\n---\n\n## Why this is different\n\nMost memory systems are either too small — a few strings in a prompt — or too magical: server processes, queues, vector stores, hidden summaries, model-specific workers, and unclear identity rules.\n\nHermes Local Memory is opinionated in the other direction:\n\n- **Local-first** — default storage is `~/.hermes/memory/local_memory.sqlite`.\n- **No memory server** — no FastAPI, Docker, Redis, Postgres, or daemon required.\n- **Agent-controlled** — Hermes is expected to inspect, curate, and maintain memory through normal tools like `memory_context`, `memory_search`, `memory_conclude`, and `memory_consolidate`.\n- **Memory is first-class** — context, peers, aliases, cards, facts, summaries, and maintenance packets are part of the agent workflow, not a passive appendix.\n- **Inspectable by design** — humans and agents can list peers, aliases, sessions, cards, messages, facts, and rendered context.\n- **Identity is data** — aliases like `telegram:1001`, `honcho:Alice`, and `user` point to canonical peers such as `alice`.\n- **Peers are agent-maintained** — scheduled peer review lets the agent map new platform identities to canonical peers or escalate ambiguous identities for human help.\n- **Raw history is preserved** — imports copy raw messages; identity repair does not rewrite historical rows unless an explicit tool says so.\n- **Consolidation is explicit and conservative** — deterministic dry-runs produce bounded plans; imported candidates are not bulk-promoted; compact cards are curated/replaced rather than grown by blindly appending every active fact.\n- **Migration-safe** — Honcho import is additive/idempotent, supports identity maps, and never mutates Honcho.\n- **Usable by agents** — CLI JSON output, clear docs, tests, and `AGENTS.md` are first-class.\n\n---\n\n## What it offers today\n\n### Hermes provider tools\n\n`LocalMemoryProvider` exposes:\n\n| Tool | Purpose |\n| --- | --- |\n| `memory_get_card` / `memory_set_card` | Read compact peer cards, or explicitly replace full cards with diffs; empty writes require `allow_empty=true`. |\n| `memory_search` | Search active durable facts through SQLite FTS5. |\n| `memory_context` | Show exactly what local memory would inject into the prompt. |\n| `memory_conclude` | Add durable facts with evidence links to the most recent synced user turn. |\n| `memory_consolidate` | Preview/apply deterministic fact lifecycle maintenance for one peer. It can promote safe candidates, supersede duplicates, and bootstrap empty cards from safe active facts; it does not append every active fact into existing cards. |\n| `memory_maintenance` | Preview/apply deterministic fact lifecycle maintenance across all subject/observer pairs; provider results are compact summaries suitable for scheduled jobs. |\n| `memory_build_peer_review_packet` / `memory_apply_peer_review_patch` | Build and apply peer-review patches so the agent can maintain aliases and escalate ambiguous identities. |\n| `memory_build_reflection_packets` / `memory_apply_reflection_patch` | Build reflection packets for stale sessions and apply evidence-linked candidate facts plus summaries. |\n| `memory_build_candidate_review_packet` / `memory_apply_candidate_review_patch` | Review noisy candidate facts safely without broad promotion. |\n| `memory_build_card_review_packet` / `memory_apply_card_review_patch` | Review compact cards and apply full-card replacement patches. |\n| `memory_build_honcho_migration_review_packet` / `memory_apply_honcho_migration_review_patch` | Review first-migration Honcho candidates and compact card rebuilds together. |\n\n### CLI capabilities\n\n`hermes-local-memory` supports:\n\n- inspect peers, aliases, sessions, cards, messages, facts, search, and rendered context\n- explicit alias repair\n- explicit fact add/retract\n- full-card replacement from JSON\n- Hermes built-in markdown memory dry-run/apply import from `USER.md` / `MEMORY.md`\n- Honcho API dry-run/apply import\n- Honcho identity maps for fragmented peers\n- reflection packets for stale raw-message windows\n- validated reflection patch dry-run/apply for candidate facts and session summaries\n- candidate review packets for safe imported fact promotion\n- validated candidate review patch dry-run/apply\n- peer review packets for agent-controlled identity maintenance\n- validated peer review patch dry-run/apply\n- conservative deterministic consolidation dry-run/apply\n- consolidation packets for Hermes Agent review\n- conservative all-pairs maintenance dry-run/apply\n- validated consolidation patch dry-run/apply\n- Hermes plugin shim installation\n\n### Data model\n\nThe SQLite store includes:\n\n- `profiles`\n- `peers`\n- `peer_aliases`\n- `sessions`\n- `session_peers`\n- `messages` + FTS\n- `facts` + FTS\n- `cards`\n- `summaries`\n\n---\n\n## Quick install for humans\n\n### Recommended: install the published package\n\nFor normal use, install the published PyPI package as a CLI tool:\n\n```bash\nuv tool install hermes-local-memory\n# or\npipx install hermes-local-memory\n```\n\nIf you are already inside a virtualenv:\n\n```bash\npip install hermes-local-memory\n```\n\nVerify:\n\n```bash\nhermes-local-memory --help\n```\n\n### Development path: clone from GitHub\n\nUse a checkout only if you want to develop, test unreleased changes, or run directly from source:\n\n```bash\ngit clone https://github.com/smarzola/hermes-local-memory.git\ncd hermes-local-memory\npython -m venv .venv\nsource .venv/bin/activate\npip install -e '.[dev]'\nPYTHONPATH=src pytest -q\nruff check .\n```\n\nRun the CLI from a checkout with:\n\n```bash\nPYTHONPATH=src python -m hermes_local_memory.cli --help\n```\n\n### Install the Hermes plugin shim\n\nIf installed from PyPI/pipx/uv:\n\n```bash\nhermes-local-memory install-shim --hermes-home ~/.hermes\n```\n\nIf running from a GitHub checkout:\n\n```bash\nPYTHONPATH=src python -m hermes_local_memory.cli install-shim --hermes-home ~/.hermes\n```\n\nThis writes:\n\n```text\n~/.hermes/plugins/local_memory/__init__.py\n```\n\nIt does **not** modify `~/.hermes/config.yaml` and does **not** switch your live memory provider.\n\n### Configure Hermes\n\nAfter validating the shim and trial DB, configure Hermes:\n\n```yaml\nmemory:\n  provider: local_memory\n```\n\nThen restart Hermes or start a fresh session.\n\n\u003e Recommended: keep your existing provider active until you have imported/inspected data in a separate trial DB.\n\nFull setup/adoption guide: [docs/setup.md](docs/setup.md).\n\n---\n\n## Basic CLI examples\n\nGlobal `--db` goes before the subcommand:\n\n```bash\nhermes-local-memory --db ~/.hermes/memory/local_memory.sqlite peers --json\n```\n\nInspect memory:\n\n```bash\nhermes-local-memory --db memory.sqlite peers --json\nhermes-local-memory --db memory.sqlite aliases --json\nhermes-local-memory --db memory.sqlite cards --peer alice --observer bob --json\nhermes-local-memory --db memory.sqlite facts --peer alice --observer bob --json\nhermes-local-memory --db memory.sqlite context \\\n  --peer alice \\\n  --observer bob \\\n  --query \"what should I remember?\"\n```\n\nAdd explicit memory:\n\n```bash\nhermes-local-memory --db memory.sqlite fact add \\\n  \"Alice prefers local-first memory systems.\" \\\n  --peer alice \\\n  --observer bob \\\n  --kind preference \\\n  --json\n```\n\nRepair an alias:\n\n```bash\nhermes-local-memory --db memory.sqlite alias add telegram:1001 \\\n  --peer alice \\\n  --source telegram \\\n  --verified \\\n  --json\n```\n\nPreview consolidation:\n\n```bash\nhermes-local-memory --db memory.sqlite consolidate \\\n  --peer alice \\\n  --observer bob \\\n  --promote-candidates \\\n  --dry-run \\\n  --json\n```\n\nApply only after review:\n\n```bash\nhermes-local-memory --db memory.sqlite consolidate \\\n  --peer alice \\\n  --observer bob \\\n  --promote-candidates \\\n  --apply \\\n  --json\n```\n\nBuild an agent review packet and apply a validated patch:\n\n```bash\nhermes-local-memory --db memory.sqlite consolidation-packet \\\n  --peer alice \\\n  --observer bob \\\n  --json \u003e /tmp/alice-packet.json\n\nhermes-local-memory --db memory.sqlite apply-patch /tmp/alice-patch.json --dry-run --json\nhermes-local-memory --db memory.sqlite apply-patch /tmp/alice-patch.json --apply --json\n```\n\nRun conservative deterministic maintenance across all subject/observer pairs:\n\n```bash\nhermes-local-memory --db memory.sqlite maintenance \\\n  --promote-candidates \\\n  --dry-run \\\n  --json\n```\n\n---\n\n## Migrating from Hermes built-in markdown memory\n\nFor users who only used Hermes' standard built-in markdown memory, migration is simpler than Honcho: import the local `USER.md` and `MEMORY.md` files from `~/.hermes/memories`.\n\nDry-run into a trial DB first:\n\n```bash\nhermes-local-memory --db ~/.hermes/memory/local_memory_trial.sqlite import hermes-markdown \\\n  --source-dir ~/.hermes/memories \\\n  --user-peer alice \\\n  --assistant-peer bob \\\n  --dry-run \\\n  --json\n```\n\nApply only after reviewing the plan:\n\n```bash\nhermes-local-memory --db ~/.hermes/memory/local_memory_trial.sqlite import hermes-markdown \\\n  --source-dir ~/.hermes/memories \\\n  --user-peer alice \\\n  --assistant-peer bob \\\n  --apply \\\n  --json\n```\n\nImport behavior:\n\n- `USER.md` entries become active user facts for `alice` observed by `bob`.\n- `USER.md` entries also become Alice's compact card for Bob.\n- `MEMORY.md` entries become active agent/self facts for `bob` observed by `bob`.\n- `MEMORY.md` entries also become Bob's self-card.\n- entries are split using Hermes' standard `§` delimiter.\n- the import is additive and idempotent; existing facts are skipped on repeated apply.\n- an existing target DB is backed up automatically unless `--no-backup` is passed.\n\nBecause markdown memory is already curated, imported facts are active by default. You can still run card review or consolidation afterward if you want a cleaner compact card before switching providers.\n\n---\n\n## Migrating from Honcho\n\nPreferred path: use the Honcho HTTP API, not direct database reads.\n\nDry-run:\n\n```bash\nhermes-local-memory --db ~/.hermes/memory/local_memory_trial.sqlite import honcho-api \\\n  --base-url http://localhost:8000/v3 \\\n  --workspace hermes \\\n  --api-key \"$HONCHO_API_KEY\" \\\n  --dry-run \\\n  --json\n```\n\nApply to a **trial DB**:\n\n```bash\nhermes-local-memory --db ~/.hermes/memory/local_memory_trial.sqlite import honcho-api \\\n  --base-url http://localhost:8000/v3 \\\n  --workspace hermes \\\n  --api-key \"$HONCHO_API_KEY\" \\\n  --apply \\\n  --json\n```\n\nUse identity maps to collapse fragmented Honcho identities into canonical local peers:\n\n```json\n{\n  \"peers\": {\n    \"honcho:1001\": \"alice\",\n    \"honcho:Alice\": \"alice\",\n    \"honcho:1002\": \"carol\",\n    \"honcho:Bob\": \"bob\"\n  },\n  \"patterns\": {\n    \"honcho:user-default*\": \"alice\"\n  },\n  \"display_names\": {\n    \"alice\": \"Alice\",\n    \"carol\": \"Carol\",\n    \"bob\": \"Bob\"\n  },\n  \"kinds\": {\n    \"alice\": \"human\",\n    \"carol\": \"human\",\n    \"bob\": \"ai\"\n  }\n}\n```\n\nThen pass:\n\n```bash\n--identity-map ~/.hermes/local-memory-identity-map.json\n```\n\nAfter import, treat Honcho candidate facts and imported cards as first-migration review material, not as disposable noise. Honcho-derived conclusions are intentionally imported as candidates and deterministic maintenance will not bulk-promote them, but the first migration should actively review high-signal memories and use selected ones to rebuild compact cards:\n\n1. in an agent session, use `memory_build_honcho_migration_review_packet` / `memory_apply_honcho_migration_review_patch` to promote selected high-signal Honcho candidates and apply a compact card rebuild in one validated review flow;\n2. outside Hermes Agent, use CLI `honcho-migration-review-packet` / `apply-honcho-migration-review-patch` for the same combined candidate/card review;\n3. use ordinary candidate/card review later for remaining noisy candidates or card cleanup.\n\nExample combined Honcho migration review packet:\n\n```bash\nhermes-local-memory --db ~/.hermes/memory/local_memory_trial.sqlite \\\n  honcho-migration-review-packet \\\n  --peer alice \\\n  --observer bob \\\n  --json\n```\n\nExample card cleanup packet:\n\n```bash\nhermes-local-memory --db ~/.hermes/memory/local_memory_trial.sqlite card-review-packet \\\n  --peer alice \\\n  --observer bob \\\n  --json \u003e /tmp/alice-card-packet.json\n```\n\nExample full-card replacement patch:\n\n```json\n{\n  \"schema\": \"hermes-local-memory.card-review-patch.v1\",\n  \"subject_peer_id\": \"alice\",\n  \"observer_peer_id\": \"bob\",\n  \"card_replace\": [\n    \"Name: Alice\",\n    \"PREFERENCE: Prefers local-first, auditable memory systems\"\n  ]\n}\n```\n\nApply only after a dry-run validation:\n\n```bash\nhermes-local-memory --db ~/.hermes/memory/local_memory_trial.sqlite apply-card-review-patch \\\n  /tmp/alice-card-patch.json \\\n  --dry-run \\\n  --json\n```\n\nSee [CLI docs](docs/cli.md) for full importer and migration-review behavior.\n\n---\n\n## How the memory flow works\n\nLocal Memory separates **raw history**, **peers**, **reflection**, **durable facts**, **compact cards**, and **agent decisions**. The agent is not merely reading a memory appendix; it is responsible for operating this memory substrate through explicit tools and auditable maintenance jobs.\n\n```text\nNormal conversation turn\n  -\u003e Hermes injects a compact source-labeled context block\n  -\u003e user/assistant messages are stored immutably as raw history\n  -\u003e explicit facts can be added immediately with evidence\n\nScheduled peer review\n  -\u003e new or unverified platform identities become peer review packets\n  -\u003e Hermes Agent maps obvious aliases to canonical peers\n  -\u003e ambiguous identities are escalated as human prompts instead of guessed\n  -\u003e Local Memory validates and applies explicit alias moves\n\nScheduled reflection / distillation\n  -\u003e stale raw-message windows become reflection packets\n  -\u003e Hermes Agent reviews the packets\n  -\u003e Local Memory validates reflection patches\n  -\u003e candidate facts and session summaries are written with evidence\n\nScheduled consolidation / maintenance\n  -\u003e candidates, active facts, cards, aliases, and summaries are reviewed across all subject/observer pairs\n  -\u003e deterministic maintenance handles only safe fact lifecycle changes\n  -\u003e Hermes Agent uses review packets/patches for card synthesis or ambiguous candidate promotion\n  -\u003e Local Memory validates and applies structured changes\n\nNext prompt injection\n  -\u003e compact card + durable facts + session summary + relevant retrieval are injected\n```\n\nThe important split is:\n\n- **Local Memory** stores, retrieves, validates, and applies auditable changes.\n- **Hermes Agent** owns memory decisions: peer mapping, reflection review, candidate promotion, card synthesis/cleanup, and ambiguous consolidation choices.\n- **Humans** are asked only when the agent cannot safely infer a peer or when policy requires approval.\n- **Hermes cron/scheduler** runs recurring peer review, reflection, and consolidation.\n\nThe profile/card is **not** the only thing injected. Context Builder v2 composes ordinary prompt context from:\n\n1. identity/session information,\n2. aliases for the current subject peer,\n3. the compact subject/observer card,\n4. active durable facts,\n5. the current session summary when available,\n6. relevant retrieved active facts for the current query.\n\nCandidate facts and raw message windows are usually **not** injected into ordinary conversations. They are primarily used during maintenance/review jobs unless explicitly requested.\n\n### Reflection, consolidation, and cards\n\nReflection is the distillation step: stale raw-message windows become evidence-backed candidate facts and session summaries. Consolidation/maintenance is the fact-lifecycle step: duplicate candidates can be superseded and high-confidence local candidates can be promoted. **Cards are compact synthesized views**, not append-only mirrors of the fact table.\n\nThat means ordinary maintenance deliberately does **not** append every active fact into a card. If a card needs cleanup or synthesis, use `card-review-packet` / `apply-card-review-patch` or a validated consolidation patch with `card_replace`. This keeps prompt context small, auditable, and human/agent-readable.\n\nImported Honcho conclusions are mixed-quality rather than worthless. They remain candidates so deterministic maintenance cannot blindly bulk-promote them, but first migration should explicitly review high-signal Honcho memories and use selected ones to rebuild cards. Large candidate-promotion counts in ordinary maintenance dry-runs should still be treated as a tooling or policy regression, not something to blindly apply.\n\nWhy maintenance is needed:\n\n- ordinary conversations create useful memories that are not explicitly saved during the turn\n- conversations also create duplicate or overlapping memories\n- imported systems can contain stale identities or noisy derived facts\n- candidate facts need promotion, superseding, or retraction\n- compact cards should stay useful instead of growing into transcripts; ordinary maintenance must not append every active fact into cards\n- raw history should remain intact while derived layers improve over time\n\nThis is why the project supports both reflection/distillation and deterministic all-pairs maintenance, orchestrated by Hermes scheduled jobs rather than hidden backend workers. Reflection creates evidence-backed candidate facts and session summaries; card synthesis remains an explicit review/patch step so cards stay compact.\n\n---\n\n## Setup checklist for agents\n\nIf a human asks an agent to install or migrate Local Memory, use the published package by default. Clone GitHub only for development or unreleased debugging.\n\n1. **Install the published CLI**\n\n   ```bash\n   uv tool install hermes-local-memory\n   # or\n   pipx install hermes-local-memory\n   hermes-local-memory --help\n   ```\n\n2. **Install the Hermes shim without switching providers**\n\n   ```bash\n   hermes-local-memory install-shim --hermes-home ~/.hermes\n   ```\n\n3. **Create or choose a trial DB**\n\n   ```bash\n   export LOCAL_MEMORY_DB=~/.hermes/memory/local_memory_trial.sqlite\n   ```\n\n4. **Import external memory only into the trial DB first**\n\n   ```bash\n   hermes-local-memory --db \"$LOCAL_MEMORY_DB\" import honcho-api \\\n     --base-url http://localhost:8000/v3 \\\n     --workspace hermes \\\n     --identity-map ~/.hermes/local-memory-identity-map.json \\\n     --dry-run \\\n     --json\n   ```\n\n5. **Review imported candidates and cards before judging context quality**\n\n   ```bash\n   hermes-local-memory --db \"$LOCAL_MEMORY_DB\" candidate-review-packet \\\n     --peer alice \\\n     --observer bob \\\n     --source honcho-api-conclusion \\\n     --limit 100 \\\n     --json \u003e /tmp/alice-candidates.json\n\n   hermes-local-memory --db \"$LOCAL_MEMORY_DB\" card-review-packet \\\n     --peer alice \\\n     --observer bob \\\n     --json \u003e /tmp/alice-card.json\n   ```\n\n   Have Hermes Agent produce validated patches, dry-run them first, and apply only narrow, reviewed changes to the trial DB.\n\n6. **Inspect identity and context**\n\n   ```bash\n   hermes-local-memory --db \"$LOCAL_MEMORY_DB\" peers --json\n   hermes-local-memory --db \"$LOCAL_MEMORY_DB\" aliases --json\n   hermes-local-memory --db \"$LOCAL_MEMORY_DB\" context \\\n     --peer alice \\\n     --observer bob \\\n     --query \"memory quality\"\n   ```\n\n7. **Set up scheduled maintenance in Hermes, not in this package**\n\n   Use the cron prompt in [Scheduled maintenance with Hermes cron](#scheduled-maintenance-with-hermes-cron). Start with the trial DB. Only move to a live DB once import, identity mapping, context, and rollback expectations are clear.\n\n8. **Only switch Hermes after validation**\n\n   ```yaml\n   memory:\n     provider: local_memory\n   ```\n\nDevelopment agents working from a checkout should run `PYTHONPATH=src python -m hermes_local_memory.cli ...` instead of `hermes-local-memory ...`.\n\nFull command reference: [docs/cli.md](docs/cli.md).\n\n---\n\n## Agent workflow\n\nAgents should treat Local Memory as an auditable system of record.\n\nBefore repairs or migration:\n\n```bash\nhermes-local-memory --db memory.sqlite peers --json\nhermes-local-memory --db memory.sqlite aliases --json\nhermes-local-memory --db memory.sqlite cards --peer \u003cpeer\u003e --observer \u003cassistant\u003e --json\nhermes-local-memory --db memory.sqlite facts --peer \u003cpeer\u003e --observer \u003cassistant\u003e --json\nhermes-local-memory --db memory.sqlite messages --peer \u003cpeer\u003e --json\nhermes-local-memory --db memory.sqlite context --peer \u003cpeer\u003e --observer \u003cassistant\u003e --query \"current task\"\n```\n\nWhen consolidating, prefer an autonomous-but-auditable agent loop:\n\n1. generate a consolidation packet or plan with enough evidence and constraints\n2. let Hermes Agent reason over it and choose the action\n3. have Hermes produce a structured patch or call the appropriate memory tool\n4. validate/diff/apply through Local Memory\n5. inspect rendered context after apply\n6. never mutate raw messages as part of consolidation\n\nAgent-assisted consolidation should follow this pattern:\n\n```text\nSQLite packet -\u003e Hermes Agent reasoning -\u003e structured patch/tool call -\u003e validation/diff -\u003e explicit or policy-approved apply\n```\n\nThe memory package should not own model calls. Hermes should.\n\n---\n\n## Scheduled peer review, reflection, and consolidation with Hermes cron\n\nRegular memory maintenance is a first-class use case. The recommended path is to let Hermes schedule an autonomous job that has enough context, clear constraints, and permission boundaries to make routine memory-quality decisions itself.\n\nThe package should stay simple and local; Hermes should own scheduling, model calls, and judgment.\n\nRecommended autonomous cadence:\n\n- run nightly for most users, or every 6 hours for high-volume agents\n- first run **peer review** so new platform identities can be mapped before downstream reflection/consolidation\n- then run **reflection/distillation** over stale sessions so ordinary conversation can become candidate facts and summaries\n- then run **all-pairs maintenance** across every subject/observer pair with cards or facts\n- inspect each pair's current card, active facts, candidate facts, aliases, summaries, and rendered context\n- apply narrow, validated fact-lifecycle changes only when the plan is clearly safe\n- use card-review or consolidation patches with full `card_replace` when a compact card needs synthesis/cleanup\n- deliver a concise report of reflected sessions, changed pairs, skipped pairs, and escalations\n- escalate individual sessions/pairs when plans are large, noisy, ambiguous, identity-confused, or would rewrite cards heavily\n\nPeer review should generally run before reflection and consolidation:\n\n```text\nnew platform identities -\u003e peer review packets -\u003e alias moves or human prompts\nraw messages -\u003e reflection packets -\u003e candidate facts + session summaries\ncandidate facts + active facts + cards -\u003e maintenance -\u003e safe fact lifecycle changes\ncard-review / consolidation patches -\u003e compact card synthesis when needed\ncompact cards + durable facts + summaries + retrieval -\u003e prompt injection\n```\n\nBefore creating or updating the cron job, install/update the packaged maintenance skill into Hermes' skills directory:\n\n```bash\nhermes-local-memory sync-skills --hermes-home ~/.hermes\n```\n\nAttach/load `local-memory-maintenance` on the Hermes cron job. Keep the cron prompt short because the full flow lives in the skill and is updated by package upgrades:\n\n```text\nUse the loaded local-memory-maintenance skill to run Hermes Local Memory maintenance.\n\nDatabase: ~/.hermes/memory/local_memory.sqlite\nMode: apply bounded, policy-safe changes after dry-run validation; skip/escalate ambiguous or large plans.\nRuntime identity: use the current Hermes memory tool context. If provider tools are unavailable, instantiate LocalMemoryProvider from the installed hermes-local-memory package with the target database and realistic platform/user/agent identity.\n\nFollow the skill's full maintenance cycle and report format. Do not duplicate the flow here. Never mutate raw messages. Never switch the live Hermes provider config.\n```\n\nA more prudent/report-only variant is also useful for new deployments or risky imports:\n\n```text\nRun the same peer review + reflection + all-pairs maintenance job, but do not apply changes. Produce only a dry-run report with unresolved peer counts, proposed alias moves, human identity questions, stale session counts, proposed candidate facts/summaries, pair counts, candidate promotions/supersedes, card-review needs, skipped items, and recommendations.\n```\n\nThis gives both modes:\n\n- **autonomous by default** for well-scoped, well-validated maintenance\n- **report-only** when a human wants extra caution\n\nTo schedule this from Hermes, run `hermes-local-memory sync-skills --hermes-home ~/.hermes` after install or update, attach/load the installed `local-memory-maintenance` skill on the recurring Hermes cron job, and keep the job prompt deployment-specific rather than duplicating the maintenance flow. Recommended starting schedule: nightly. High-volume deployments can move to every 6 hours after the dry-run reports look clean.\n\n## Documentation\n\n- [Setup and adoption guide](docs/setup.md)\n- [CLI reference](docs/cli.md)\n- [Features](docs/features.md)\n- [Design](docs/design.md)\n- [Release checklist](docs/release.md)\n- [Contributing](CONTRIBUTING.md)\n- [Agent instructions](AGENTS.md)\n\n---\n\n## Repository layout\n\n```text\nsrc/hermes_local_memory/\n  cli.py             CLI for inspection, repair, import, consolidation, shim install\n  consolidation.py   Deterministic consolidation planner/apply logic\n  peer_review.py     Agent peer/alias review packet and patch logic\n  hermes_markdown_import.py  Hermes USER.md / MEMORY.md importer\n  hermes_plugin.py   Hermes user-plugin shim renderer\n  honcho_api.py      stdlib Honcho HTTP API exporter\n  honcho_import.py   Honcho import planner/apply logic + identity maps\n  provider.py        Hermes-compatible provider lifecycle and tools\n  schema.py          SQLite schema bootstrap\n  store.py           SQLite store and deterministic retrieval core\n\ntests/\n  test_*.py          Store, provider, CLI, import, plugin, consolidation tests\n```\n\n---\n\n## Development\n\nClone the repository before running development commands:\n\n```bash\ngit clone https://github.com/smarzola/hermes-local-memory.git\ncd hermes-local-memory\npython -m venv .venv\nsource .venv/bin/activate\npip install -e '.[dev]'\nPYTHONPATH=src pytest -q\nruff check .\nPYTHONPATH=src python -m compileall -q src tests\n```\n\nBuild package artifacts before release:\n\n```bash\nuv build\n# or: python -m build\n```\n\nCI runs on Python 3.11, 3.12, 3.13, and 3.14. Release creation and PyPI publication are handled by the tag-triggered GitHub Actions workflow; local builds are preflight checks only. See [docs/release.md](docs/release.md) for the release checklist.\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmarzola%2Fhermes-local-memory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmarzola%2Fhermes-local-memory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmarzola%2Fhermes-local-memory/lists"}