All plugins

goneby

Retroactive project memory for LLM agents. Captures every turn into an encrypted per-project write-ahead log (zero tokens during work), then at project close walks the log backward from the shipped product — the oracle — keeping only entries that verifiably contributed; survivors are embedded (MRL-truncated) and stored in Valkey or Qdrant for semantic search in later sessions. General plugin: coexists with any memory provider instead of replacing it. Disclosure — On by default, GoneBy records every chat turn of each project (your messages, the assistant's replies and tool output text) into an encrypted log under your Hermes profile's plugin-data folder. When you close a project, it sends the log to your configured model to choose which entries to keep, sends the kept text to the embedding endpoint you configure (default localhost), and stores it unencrypted in your Valkey or Qdrant database (default localhost). Turn capture off with the auto_capture setting or /goneby gate off.

rahlquistMemoryv1.1.1Updated 20 hours ago

About

Retroactive project memory for LLM agents. Captures every turn into an encrypted per-project write-ahead log (zero tokens during work), then at project close walks the log backward from the shipped product — the oracle — keeping only entries that verifiably contributed; survivors are embedded (MRL-truncated) and stored in Valkey or Qdrant for semantic search in later sessions. General plugin: coexists with any memory provider instead of replacing it. Disclosure — On by default, GoneBy records every chat turn of each project (your messages, the assistant's replies and tool output text) into an encrypted log under your Hermes profile's plugin-data folder. When you close a project, it sends the log to your configured model to choose which entries to keep, sends the kept text to the embedding endpoint you configure (default localhost), and stores it unencrypted in your Valkey or Qdrant database (default localhost). Turn capture off with the auto_capture setting or /goneby gate off.

GoneBy — Retroactive Project Memory for LLM Agents

GoneBy is a library, MCP server, and Hermes plugin that captures LLM project
output every turn into an encrypted write-ahead log, then retroactively
filters and stores what actually mattered — judged backward from the shipped
product — for semantic search in later sessions.

→ Setting up the full stack from zero (llama.cpp, the embedding model,
Valkey, keys, smoke test): docs/SETUP.md.

→ Full documentation of the mechanism, benefits, and every user option:
docs/OVERVIEW.md.

→ How the idea came to be — the September session, the inversion, and why
it runs alongside your memory system: docs/IDEATION.md.

Watch

GoneBy — 1:40 narrated explainer

The Rewind — the problem, the backward walk, and the four phases, narrated
and captioned. Release asset (MP4, 13 MB)

How It Works

  1. Capture (WAL): Every turn is appended to an encrypted per-project
    Write-Ahead Log at pre_llm_call boundaries — before the host compacts
    the transcript, so nothing is lost to the rewrite. No filtering, no LLM
    calls — just append.
  2. Filter (Backward Walk): At project close, walk backward through the WAL using the shipped product as the oracle to determine which entries were actually relevant.
  3. Store (Embed + Vector DB): Embed the surviving entries and upsert them into Valkey (default) or Qdrant.
  4. Retrieve: Future sessions query the store semantically.

The capture phase costs zero tokens. All inference is deferred to the single backward-walk pass and the embedding call at store time.

Requirements

ComponentRequirementNotes
Python3.11+
Encryption key32 bytesgoneby generate-key
Embedding serverAny OpenAI-compatible /v1/embeddingsllama.cpp recommended
Vector storeValkey (default) or Qdrant

Embedding server

GoneBy talks to any server exposing POST /v1/embeddings. Recommended: Qwen3-Embedding-0.6B via llama.cpp, running locally.

# Start the embedding server (CPU is fine for this model size)
llama-server \
  -m ~/models/Qwen3-Embedding-0.6B-Q8_0.gguf \
  --embedding \
  --host 127.0.0.1 \
  --port 8081 \
  -c 4096

No --pooling flag is needed — the pooling type ships in the GGUF metadata.
Get llama.cpp and the model from the URLs in
docs/SETUP.md §3.

Verify:

curl http://localhost:8081/v1/models
goneby status

MRL (Matryoshka truncation). The model emits 1024 dimensions. GoneBy truncates to
GONEBY_EMBEDDING_DIMENSIONS (default 512) and renormalizes, halving storage while
retaining ~97% of retrieval quality. Raise it to 1024 for maximum fidelity; drop to 256
for large stores. Truncation happens before normalization so the stored vectors are
unit-length and cosine similarity is a plain dot product.

Quick Start

uv venv .venv && uv pip install --python .venv/bin/python -e ".[mcp,valkey,qdrant]"

export GONEBY_ENCRYPTION_KEY=$(.venv/bin/goneby generate-key | head -1 | awk '{print $NF}')
goneby status
goneby serve

Configuration

VariableDefaultDescription
GONEBY_ENCRYPTION_KEY(required)32-byte hex key for ChaCha20-Poly1305
GONEBY_DATA_DIRsee belowExplicit data dir (WAL + policy file). Overrides the context default
GONEBY_WAL_PATH<data-dir>/walEncrypted WAL location
HERMES_HOME~/.hermesHermes profile home. Under a profile the data dir is <HERMES_HOME>/plugin-data/goneby; the standalone CLI/MCP falls back to ~/.goneby
GONEBY_PROJECTdefaultProject namespace for stored memories
GONEBY_VECTOR_BACKENDvalkeyvalkey or qdrant
GONEBY_VALKEY_HOST / _PORT / _DBlocalhost / 6379 / 0Valkey connection
GONEBY_QDRANT_HOST / _PORTlocalhost / 6333Qdrant connection
GONEBY_QDRANT_COLLECTIONgonebyQdrant collection
GONEBY_EMBEDDING_BASE_URLhttp://localhost:8081/v1Embedding server
GONEBY_EMBEDDING_MODELqwen3-embedding-0.6bModel name sent to the server
GONEBY_EMBEDDING_API_KEY(none)Bearer token, for hosted embedders
GONEBY_EMBEDDING_DIMENSIONS512MRL truncation target
GONEBY_EMBEDDING_BATCH_SIZE16Texts per request
GONEBY_LLM_PROVIDERopenaiJudge provider for walk_backward (standalone): openai (any OpenAI-compatible server) or anthropic (needs goneby[anthropic])
GONEBY_LLM_BASE_URL(none)Chat-completions base URL for the judge — unset means walk_backward errors until configured
GONEBY_LLM_MODEL(none)Judge model name — GoneBy never defaults to a vendor model
GONEBY_LLM_API_KEY(none)Bearer token for the judge endpoint

MCP Tools

ToolPurpose
wall_append(content, entry_type)Append to the encrypted WAL — call at each compaction. Zero token cost.
wall_read()Review all captured entries
walk_backward(mvp_text)Filter the WAL against the shipped product. Returns kept entries + stats.
store_memory(entries)Embed and upsert walked entries. Idempotent — IDs are content-derived.
query_memory(query, top_k, min_score)Semantic search over stored memories
generate_key()Generate a new encryption key
status()Config, WAL stats, and a live health probe of both backends

Typical session

wall_append(<output since last compaction>, entry_type="note")
... work continues ...
walk_backward(<shipped MVP description>)   # at project close
store_memory(<kept_entries>)
query_memory(<question in a later session>)

Hermes plugin

GoneBy ships a Hermes plugin that makes capture and recall automatic — the agent does not have to remember to call anything.

~/.hermes/plugins/goneby/
├── plugin.yaml      # manifest: declares tools + hooks
├── __init__.py      # register(ctx)
├── adapter.py       # tools, hooks, capture/recall logic
└── pyproject.toml   # declares the goneby dependency for PM

Install by copying the plugin/ directory to ~/.hermes/plugins/goneby/, then:

hermes plugins validate ~/.hermes/plugins/goneby   # expect overall ok: True
hermes plugins enable goneby

What the hooks do

HookBehavior
pre_llm_callCaptures messages not yet seen into this project's WAL (skips system/tool roles). Also performs recall when GONEBY_AUTO_RECALL=true.
post_compactionRecords a compaction-boundary marker so the WAL reflects the project's shape.

Capture is per-turn rather than per-compaction: post_compaction fires after the transcript is rewritten, so the dropped messages are already gone. pre_llm_call hands us the full conversation_history before that happens, which is a superset and loses nothing.

Capture is idempotent — messages are keyed on message_uid when present, else a role+content hash — so a turn that appears in several pre_llm_call payloads is stored once.

Configuration (plugin)

VariableDefaultDescription
GONEBY_AUTO_CAPTUREtrueCapture turns into the WAL automatically
GONEBY_AUTO_RECALLfalseInject relevant memories into every turn
GONEBY_RECALL_MIN_CHARS12Skip recall for turns shorter than this
GONEBY_RECALL_TOP_K3Memories injected per turn when recall is on

GONEBY_AUTO_RECALL defaults off because a semantic search on every turn costs latency; the agent already has query_memory.

Project isolation

Each project writes its own WAL (<data-dir>/wal/<project>.wal), so a backward walk for one project never sees another's evidence. Retrieval is scoped by default; pass scope="all" for deliberate cross-project lookup.

The project name comes from GONEBY_PROJECT. To key on the working directory instead, point it at a stable slug — the plugin flattens paths safely.

Tools

The same six tools the MCP server exposes, registered as first-class Hermes tools: wall_append, wall_read, walk_backward, store_memory, query_memory, goneby_status.

Under Hermes, walk_backward judges relevance through ctx.llm.complete_structured — it borrows the user's active model and auth, so there is no separate API key and no hardcoded provider. Standalone (MCP server), the judge is configured, never defaulted: point GONEBY_LLM_BASE_URL/GONEBY_LLM_MODEL at any OpenAI-compatible chat endpoint, or use the opt-in goneby[anthropic] extra.

Security

  • WAL entries are encrypted independently with ChaCha20-Poly1305 and a random 96-bit nonce. v2 lines additionally bind file name, directory token, and sequence as additional-authenticated-data: deleting, reordering, or copying lines from another WAL is detected ([GAP]/out-of-order markers, failed tags). A deletion at the very end of a file cannot be detected without a head-hash chain — documented limitation, future work.
  • A wrong key or damaged line yields a CORRUPTED marker (wrong key is called out via the .keyid sidecar) rather than aborting the read or leaking plaintext. Legacy pre-v2 lines stay readable and are flagged integrity: unbound.
  • The searchable store is plaintext by design. Walk survivors are embedded and stored with their text in Valkey/Qdrant, because semantic search and answers need the content. What the encryption protects: the raw transcript log at rest, and copies/backups of it. Protect the vector store with its own access controls.
  • Losing the key means losing the WAL. Store it in Bitwarden or the Hermes vault, not in the repo.

Capture policy

Capture is on for everything by default (mode=all), with four controls —
most specific wins:

ControlScopeSet via
master gateeverywhere, persisted/goneby gate on|off, goneby gate on|off, <data-dir>/config.json
platform killone gateway (telegram, discord, cli, desktop...)/goneby platform telegram off, goneby platform disable telegram, GONEBY_DISABLED_PLATFORMS=telegram,discord (env is additive, not persisted)
project markerone repo — .goneby.json at the project root, team-visible, travels with the repo/goneby enable [path], /goneby disable [path], goneby project enable PATH, goneby_project tool
user overrideone project, personal — <data-dir>/config.json projects map (used when no marker exists or the repo isn't writable)goneby project enable --project SLUG, goneby_project tool fallback

Switching the whole system to disable-by-default: /goneby mode opt-in or
goneby mode opt-in — then only projects with an enabling marker/override
capture. mode all (default) captures everything not excluded above.

Project identity: the plugin resolves a session's project from Hermes'
ctx.session_cwd() (a public plugin-context accessor) plus the plugin's own
nearest-.git-ancestor walk — no Hermes internals are read. The
repo directory name becomes the WAL slug, so per-project WALs are real, not
aspirational. Sessions with no resolvable context fall back to
GONEBY_PROJECT/default.

Everything persists in <data-dir>/config.json (GONEBY_CONFIG_PATH to move
it). goneby_status and /goneby status show the effective decision.

Architecture

┌──────────────────────────────────────────────────────────────┐
│                    LLM Agent (Hermes)                         │
│   context full → wall_append() → context compacted            │
└───────────────────────────┬──────────────────────────────────┘
                            │ zero token cost
                            ▼
              ┌──────────────────────────────┐
              │  Encrypted WAL (ChaCha20)    │  append-only
              └──────────────┬───────────────┘
                             │ at project close
                             ▼
   Shipped MVP ──► Backward Walk ──► LLM Judge ──► Deduplicate
   (oracle)         newest → oldest
                             │
                             ▼
              ┌──────────────────────────────┐
              │ Qwen3-Embedding-0.6B         │  MRL → 512 dims
              │ llama.cpp :8081              │  local, no API cost
              └──────────────┬───────────────┘
                             ▼
              ┌──────────────────────────────┐
              │ Valkey (default) | Qdrant    │  cosine search
              └──────────────────────────────┘

Full diagram: docs/architecture.html (open in any browser).

Development

uv pip install --python .venv/bin/python -e ".[mcp,valkey,qdrant,dev]"
.venv/bin/python -m pytest tests/ -q
.venv/bin/python -m ruff check .

The test suite runs a fake OpenAI-compatible embedding server, so no model or vector
database is required. The fake is not semantic — it validates plumbing (batch
ordering, MRL truncation, normalization, round trips, idempotency), not retrieval
quality. Verify ranking against a real model before trusting it.

scripts/live_check.py exercises the embedder plumbing (batching, MRL,
normalization, round trips) against a fake vector server on :8081 —
it validates transport, not ranking quality.

Deployment guidance

GoneBy has three moving parts: the embedding server, the vector
backend
, and (for Hermes users) the plugin. Run the first two as
long-lived local services however your machine supervises services — a
systemd user unit, docker compose, launchd, or plain nohup all work.
Example systemd user unit for a llama.cpp embedder:

# ~/.config/systemd/user/goneby-embedder.service
[Unit]
Description=GoneBy embedding server
[Service]
ExecStart=%h/llama.cpp/llama-server -m %h/models/qwen3-embedding.gguf \
  --embedding --host 127.0.0.1 --port 8081 -c 4096
Restart=on-failure
[Install]
WantedBy=default.target

Guidelines that matter more than the exact paths:

  • Bind everything to 127.0.0.1. The embedder and valkey are local
    services; valkey additionally runs with --protected-mode yes.
  • Point Hermes at the config via GONEBY_* variables in
    ~/.hermes/.env (Hermes' own env file, mode 600), including
    GONEBY_ENCRYPTION_KEY — generated with goneby generate-key and
    recorded nowhere else. Losing it means losing every WAL.
  • CPU is sufficient for the recommended 0.6B embedding model.
  • goneby status probes the whole chain (config + live embedder) — make it
    part of any health check.

Self-contained plugin tree (Hermes)

The repository root is the plugin directory: plugin.yaml, __init__.py
and adapter.py sit at the root next to src/goneby, and the root
pyproject.toml declares the runtime dependencies (cryptography, httpx,
valkey). A Hermes install — catalog entry, git URL, or a pinned --ref —
copies this one reviewed tree, so the plugin and the library can never drift
apart and nothing has to be edited after cloning. There is no registry
dependency, no path source, and no network fetch beyond the clone itself.

Verified reference deployment

A full local deployment (llama.cpp + Qwen3-Embedding-0.6B Q8_0 + valkey,
plugin enabled on a live gateway) was verified end-to-end on 2026-11-10:
real-model ranking margin related/unrelated cosine 0.67/0.25, correct top
hit, project-scoped isolation proven against the store, WAL ciphertext at
rest. The unit suite uses a fake embedder and validates plumbing, not
ranking — always sanity-check ranking with goneby status plus a real
query when you stand a new machine up.

License

Apache 2.0

README from the reviewed commit 99a7099; it updates when the author re-pins.

Developer Mode

Explore built-in Hermes toolsets and actions.

HermesAgent

Developer?

Create a Hermes extension for Desktop or agent workflows.

Developer Section