hermes-agent/plugin-catalog/holographic.yaml

name: holographic
title: Holographic
repo: https://github.com/itpartypattaya/hermes-plugin-holographic
sha: 6fe7d424cdc1b197e4a1f2dc1542e9e3869bf4f0
version: "0.26.4"
description: "Local fact-store memory provider: SQLite with FTS5 keyword search (word forms in English, Russian, Spanish, French, Portuguese, Indonesian, German, Hindi, Arabic, Bengali, Italian, Turkish, Polish and Dutch; Russian and English words of the same root at a lower weight, from bundled DerivBase.Ru (Apache-2.0) and Open English Wordnet (CC BY 4.0) pairs; German compounds and German and Spanish irregular verb forms from bundled Wikidata Lexemes tables (CC0); Chinese, Japanese, Korean and Thai by character n-grams, Chinese also split into words with jieba's dictionary (MIT), Traditional and Simplified Chinese compared as one through a bundled OpenCC table (Apache-2.0), Japanese spelling variants through SudachiDict's (Apache-2.0); synonyms through keywords the agent gives when it stores a fact), trust scores, entities with aliases and HRR (holographic reduced representation) recall, with no API key, network or model calls unless an optional online feature is switched on: search by meaning (embeddings: on) or rescoring by a cross-encoder (rerank: on), both off by default. The provider that shipped in-tree as plugins/memory/holographic, with the same provider name, config (plugins.hermes-memory-store) and memory_store.db, so `hermes update` moves existing users onto it; a file without merges keeps history schema 1; the first merge raises it to schema 2, after which writers of 0.15-0.18 refuse it until 0.19.0 or a pre-merge backup is restored. Taken over from Nous Research's handoff copy (NousResearch/hermes-plugin-holographic) and maintained by itpartypattaya; since 0.1.1 it fixes probe/reason/related/contradict, non-atomic writes and the never-written retrieval_count, gates recall by relevance without repeats, flags duplicates and conflicts when a fact is added, and honours the provider contract (read-only subagent contexts, hermes_home, mirror metadata, backup_paths); since 0.8.0 it keeps the history of every fact (change / end / correct / revert, search and list as_of a date) and `forget` erases a fact with all its versions from the file; since 0.16.0 a name guessed from a fact's text must be shaped like one and stays provisional until a second fact or a person confirms it, and entities can be renamed or deleted (the facts stay). Since 0.18.0 an optional, experimental second stage reorders the recall candidates with a cross-encoder at a /v1/rerank endpoint that answers in Cohere's shape without a key, such as llama-server (rerank: on, off by default). It does not raise hits: on the maintainer's held-out set (126 questions) it cut non-target facts in the top five by about 40 % and lines per turn by about a third, and lost about one target per hundred questions. Disclosure — local only unless an optional online feature (search by meaning or rescoring) is switched on: reads and writes one SQLite file per profile ($HERMES_HOME/memory_store.db unless db_path says otherwise), or with scope: user / chat / thread one file per user or chat in holographic-users/ or holographic-chats/ next to it; each fact version records where it was written (platform, chat type, chat and thread id, session id, the turn author's id and display name, and whether the person said it or the agent inferred it; never chat titles), shown in full by list, history and export and not in recall unless recall_source: short (date, display name, this or another chat); each confirmation of a fact by a person keeps its time, session id and that person's id (no text); forget deletes that and the confirmations with the fact and keeps only an HMAC of the text, keyed by a random key stored in the same file, as a tombstone; delete_entity removes a name, its aliases and links from the entity index (never a fact) and keeps an HMAC of each name the same way (not of an alias only a fact's text gave, which goes without one), and both rewrite the file so freed pages keep no copy; the first writable open after an upgrade that changes the extraction rules relinks the facts to their entities under the new rules (stores up to 2,000 facts and 500,000 characters; larger ones on fact_store rebuild_entities), changing only the names it guessed and their links, never a fact, a declared name or an alias someone gave; subagents never write, but a cron job's explicit fact_store / fact_feedback calls do unless cron_writes: false (on by default); no subprocesses or telemetry (at the debug log level the recall stages log fact ids and scores, never text), and no network calls or credentials unless embeddings: on or rerank: on (both off by default). With embeddings: on, the text of facts, and of messages and fact_store search queries that are not greetings, goes to the OpenAI-compatible embeddings endpoint the user configures, also after cron turns while cron_writes is on (embedding_url; https, plain http only to localhost, a private or link-local address, or a local host name such as one without a dot or ending in .local), with the key read from the environment variable the user names (embedding_key_env, OPENAI_API_KEY unless set, sent as a Bearer token to whatever embedding_url is configured, never stored in config) and no redirects followed; facts that recall would not inject, and facts and messages that look like they hold a secret (checked by pattern, best effort), are not sent; the vectors are kept in the same file (table fact_embeddings), deleted with their fact by forget / end / remove and all of them by the next writable session after the option is switched off; the provider keeps what it received under its own terms; with rerank: on, before a turn the user's message and up to rerank_top_k (40) candidate fact texts, and for a fact_store search its query and results, go to the rerank endpoint the user configures (rerank_url; https, plain http only to localhost, a private or link-local address, or a local host name), with no credentials and no redirects followed; facts that recall would not inject or that look like they hold a secret, and queries that hold one, are not sent; a failure or a slow answer gives the recall of rerank: off and pauses the endpoint (60 s, doubling to 900 s); nothing the endpoint returns is stored; the bundled language dictionaries are gzip-compressed plain-text word lists; with auto_extract on (off by default) user sentences that state a preference or decision are stored. Since 0.19.0, fact_store merge combines duplicate facts in one transaction while keeping each copy's history, sources and confirmations under its original id. The retained fact keeps its own text, trust and origin; copies leave current search and recall. Optional expect pins the exact shown versions and refuses changed participants without a write. Scheduled jobs can merge only copies created in their own session. Forgetting the retained fact also erases its merged copies. Merge is local and makes no new network or model calls. Version 0.19.1 adds strict tooling for comparing recorded margins; the normal RECALL_MARGIN remains 1.0. Version 0.19.2 closes a timed-out rerank or embeddings request socket so a server dripping response headers does not keep its worker alive. During TLS wrapping, cancellation is retained but the handshake can continue until its own socket timeout; DNS resolution is outside socket cancellation. Version 0.20.0 adds an opt-in local task-outcome journal and the memory-provider tool fact_experience: emitted and candidate fact/version identifiers, an optional short task and correction, outcome/reason and optional corrected-source references. It is separate from trust, origin and ranking. Agent reports are not authenticated human confirmations. Collection and detailed tracing are off by default; retention is bounded to 30 days and 1000 attempts per store, with up to 10 revisions per attempt. Forgetting any referenced fact removes the dependent attempt and outcome from the store. No new model, network or credential use; synchronous local writes add latency. PR #45 also loads NumPy on first use outside the plugin-loader lock; concurrent first callers wait for import completion. Version 0.20.1 limits SQLite busy waits for the optional journal and retries transient contention once. Failed receipts are reported and are not queued; the SQLite timeout is not a full search deadline. Version 0.20.2 writes no receipt for a prefetch that emits nothing, applies journal retention whenever a writer opens the store (also with the journal off) and scrubs removed outcome text from the file like a forgotten fact. Version 0.20.3 adds one system-prompt line, only with the journal on, asking the agent to record an outcome when the person corrects an answer that used recalled facts (an agent report, not human confirmation). Version 0.21.0 adds an opt-in prefetch_max_tokens budget for the recalled block: facts that do not fit are left out whole, never cut; off by default. Version 0.22.0 keeps entity links honest on a text change: a new entities list replaces the declared names, and a declared name the new text no longer says is dropped; revert restores a version's declared names from an additive version_names table (names with keyed hashes, removed with the version and by delete_entity in every spelling a tombstone covers, including by older releases through triggers). Version 0.22.1 makes the secret/instruction screen about 30× faster on long texts with the same decisions (patterns unchanged; a prefilter chooses where they are tried). Version 0.22.2 sends a slow reranker only as many of the first candidates as its measured speed answers in half rerank_timeout (at least two), so a large pool no longer times out and pauses the endpoint; the candidates not sent keep their order behind the scored ones. Version 0.23.0 stops feedback (helpful/unhelpful) from refreshing a fact's age: optional temporal decay counts from when the current version was recorded, and updated_at changes only when the fact itself does; a correction with a new text (correct / update content) starts at its origin's trust without the old text's helpful marks, recalls and confirmations, like change, while a date-only correction keeps them and revert restores the old trust. Version 0.23.1 takes a correction that journal retention removed off the disk on the open connection (the file rewrite runs after the receipt write, with busy timeout 0 at every step) and clears only the rewrite mark it served. Version 0.24.0 adds two experimental features, both off by default and with no new network, model or credential use: memory_map.py, a command-line exporter nothing in the provider calls, which prints one store as a read-only JSON snapshot for a person to read (opened mode=ro in one read transaction; a forgotten fact is its id and date only; corrected versions and texts the safety screen hides carry no text; with --config it reads config.yaml's search settings, with --hermes-home the hermes-dreaming files about the profile store), whose output holds the facts' texts and so is personal data; and prefetch_clause_coverage: on, which gives each of two separate Russian or English questions in one message a second look at the facts the coverage gate left out. Version 0.25.0 limits the memory map export to 1000 facts and 300 names by default (--max-facts / --max-entities, 0 for none) and says what it cut in SNAP.limits; nothing else changes. Version 0.25.1 fixes recall by meaning dropping a fact that names a short Russian name in another grammatical case than the message (Eva as «Ева» / «Еву»): the name now also meets a capitalized word of the fact that may be a case form of it. Version 0.25.2 reads that word by its case ending rather than a short stem: names whose stem changes meet their forms («Лев» / «Льва»), and different names that only shared a short stem («Аня» / «Анна») no longer meet; nothing else changes. Version 0.25.3 no longer imports NumPy when the provider starts (the first search that needs it does, as does opening a store whose vectors need re-encoding) and treats a NumPy that is installed but fails to import as missing, so recall goes on by words; finds a Latin word written into Chinese, Japanese, Korean or Thai text by itself; refuses at write, and leaves out of recall, a prompt addressed to an assistant and the agent's report of its own steps; and auto_extract (off by default) no longer stores a reply such as \"I like that\" as a preference; no change to defaults, schema or network behaviour. Version 0.26.0 adds an experimental presence gate, prefetch_presence_gate (off by default): with it on, a fact this provider injected is held back past the six-turn repeat window only while the model can verifiably still see it (its exact recall line inside a <memory-context> block the core fenced, or its fact id and text in a fact_store result), reading only the messages the core already passes to sync_turn, with no new storage, network, model or credential use; tool results now carry raw Unicode instead of Unicode escape sequences (a payload that cannot be encoded keeps the escaped form); change names the keywords it drops and correct writes the keywords it is given; with the gate off, recall is unchanged. Version 0.26.1 fixes that gate after an independent review: a sync the core queued before a compaction no longer counts as the current view, a fact the compaction removed is recalled again once a fresh view no longer shows it, a compaction that fails no longer switches the gate off for the session, a late sync keeps its own turn, and a fact_store history result counts as the fact being visible; with the gate off nothing changes. Version 0.26.2: with the task-outcome journal on (off by default), a prefetch that only refreshes facts the session already holds records no new attempt and carries no Memory attempt line, so a repeated block adds nothing new to the context. Version 0.26.3: with the journal and the presence gate on, a delivery whose attempt could not be written after a compaction no longer stops that fact from recording attempts later. Version 0.26.4 fixes the presence gate after a second independent review: two late syncs in a row each keep their own turn, a quiet session that compacted leaves no lasting state, and a refresh no longer keeps token-budget room for an attempt line it does not carry."
maintainer: itpartypattaya
tier: community
category: memory
requires_hermes: ">=0.21.5"
docs_url: https://github.com/itpartypattaya/hermes-plugin-holographic/blob/6fe7d424cdc1b197e4a1f2dc1542e9e3869bf4f0/README.md
known_issues:
- "Word forms are matched by stems, not a dictionary: an irregular form can miss (ponies / pony). A synonym is found only if the fact's keywords name it, unless the optional online search by meaning is on; facts stored without keywords (older ones, auto_extract) need `enrich`."
- "Arabic, Indic scripts, Indonesian, German, Turkish, Polish and Dutch are matched by scanning the facts' text: the first such search after start analyses every fact (about 1-1.5 s at 5,000 facts, 4-6 s at 20,000); stores without such facts never scan. The bundled dictionaries load on the first word of their language (Chinese about 0.2 s and 30 MB)."
- "forget cleans the database file only: Hermes session history, `hermes backup` archives and copies other tools made are not rewritten (tools can read the `forgotten` table and clean their own copies by fact id)."
- "rerank: on is experimental and does not raise hits. On the maintainer's held-out set it lost one target in 126 questions with embeddings off and two with them on, on questions where several facts of one kind compete, against about 40 % fewer non-target facts. Each turn waits for one rerank call: on 4 CPU threads about 120 ms median with jina-reranker-v2-base-multilingual and 340 ms with bge-reranker-v2-m3, capped by rerank_timeout (3 s, lower with embeddings on so that both fit the core's 8 s prefetch budget). The suggested CPU model, jina-reranker-v2-base-multilingual, is CC-BY-NC-4.0 (non-commercial use only); bge-reranker-v2-m3 is Apache-2.0. The plugin ships no model. It sends no key, so a cloud rerank API that requires one (Cohere, Jina) refuses every call; it is tested with llama-server."
- "After the first merge the file uses history schema 2. Downgrading to a writer below 0.19.0 disables memory for that file until 0.19.0+ is restored or a pre-merge backup is used; manually lowering the schema mark is unsafe. There is no automatic unmerge. In this first release merged copies keep separate historical ids and confirmations are not pooled into the retained fact's origin counts."
- "memory_map.py (experimental, off unless run) writes the stored facts' texts to its output: a page or file made from it must stay behind a password and is not reached by a later forget. Its JSON format may change without a deprecation period. prefetch_clause_coverage (experimental, off) rescued no facts on one live install's history (5,081 messages) and is kept off there."
capabilities:
  provides_tools: []
  provides_hooks: []
  provides_middleware: []
  requires_env: []