SAME Memory for Hermes Agent

A memory system that keeps receipts.

A Hermes Agent memory provider plugin powered by SAME — a local-first knowledge vault with provenance, trust state, and content-aware decay.

---

The problem

Most agent memory systems are black boxes. They tell you what they remember. They don't tell you what failed to save, what went stale months ago, what got silently superseded by a newer decision, or what's been contradicted but never flagged.

So when your agent confidently says "we decided to use JWT" — and it's actually wrong, or three weeks out of date, or from a session that crashed before the decision was saved — you have no way to trace where that "memory" came from. You only catch it when something breaks.

What SAME does

SAME shows its work. Every recall comes with receipts:

• Provenance — which session wrote it, which agent, when. Trace any fact back to the moment it was saved.
• Trust state — validated, unknown, stale, or contradicted. Stale notes get a 25% confidence penalty. Contradicted notes get 60% off. They're still searchable for audit, but the agent stops surfacing them as fresh truth.
• Content-aware decay — decisions never decay. Research lasts 90 days. Handoffs fade in 30. Notes in 60. Half-life is exponential and tuned to how long that type of content actually stays valid.
• Confidence scoring — every result carries a 0.0–1.0 score with the math behind it: type baseline + recency + access boost + trust multiplier.

You stop trusting memory blindly. You audit it the way you audit code.

Also worth knowing

• Local-first — no cloud, no API keys, no telemetry. SQLite + local embeddings via Ollama.
• Cross-agent — one vault works across Hermes, Claude Code, Cursor, and any MCP client.
• Single static binary — no Python dependency hell, no model server orchestration.

Install

Prerequisites:

1. SAME binary — brew install sgx-labs/tap/same (or other install methods)
2. Initialized vault — same init
3. Hermes Agent v0.7.0+

Clone the plugin:

git clone https://github.com/sgx-labs/hermes-same-memory \
  ~/.hermes/plugins/memory/same

Activate:

hermes memory setup            # interactive wizard
# or
hermes config set memory.provider same
export SAME_VAULT_PATH=/path/to/your/vault

That's it. The plugin starts working on the next session.

Configuration

Variable	Default	Purpose
SAME_VAULT_PATH	(required)	Path to your initialized SAME vault
SAME_BINARY	same	Path to the same binary if not on PATH
SAME_AGENT	hermes	Attribution name written to provenance

Or use ~/.hermes/same/config.json:

{
  "vault_path": "/path/to/vault",
  "binary": "same",
  "agent": "hermes"
}

How it works

┌─────────────┐    prefetch     ┌──────────────┐    JSON-RPC     ┌──────────┐
│   Hermes    │────────────────▶│   plugin     │────────────────▶│ same mcp │
│   Agent     │◀────context─────│              │◀────results─────│          │
└─────────────┘                 └──────────────┘                 └──────────┘
                                                                       │
                                                                       ▼
                                                                  ┌─────────┐
                                                                  │  vault  │
                                                                  └─────────┘

The plugin starts same mcp as a persistent subprocess and communicates over stdio. One process per session, no repeated startup cost. If the subprocess dies between turns, it auto-restarts.

Search results come with receipts inline — source path, content type, trust state, confidence score, last-modified timestamp. The agent sees the metadata, not just the content.

Lifecycle hooks (automatic):

Hook	What it does
prefetch	Searches vault before every turn, injects ranked context with trust metadata
on_session_end	Generates structured handoff notes (requested, done, pending)
on_pre_compress	Persists context to vault before compression discards it
on_memory_write	Mirrors MEMORY.md / USER.md writes to the vault
on_turn_start	Auto-restarts the MCP subprocess if it died

Agent tools:

Tool	Description
same_search	Semantic search with trust state metadata
same_save_note	Save markdown notes with provenance tracking
same_save_decision	Structured decision logging with attribution
same_get_note	Read full note content by path
same_health	Vault health and index status

Vault setup tip

Add a .sameignore to your vault root before your first index. Without it, framework docs and node_modules will dominate search results.

Templates for common project types are at: https://github.com/sgx-labs/statelessagent/tree/main/templates/sameignore

Security

• Secret redaction in prefetch output (API keys, tokens, JWTs)
• Prompt injection filtering — notes matching instruction patterns are excluded from auto-recall
• Minimal subprocess env — only PATH, HOME, TMPDIR, LANG, OLLAMA_URL passed to same mcp
• Path traversal blocked at the SAME binary level

Dependencies

Zero new pip dependencies. The plugin uses only Python stdlib. The same binary handles SQLite storage, embeddings, and search — installed separately via Homebrew, npm, or curl.

Links

• SAME: https://github.com/sgx-labs/statelessagent
• Documentation: https://statelessagent.com
• Issues: https://github.com/sgx-labs/hermes-same-memory/issues

License

MIT (this plugin) · BUSL-1.1 (SAME binary)