Persistent Memory contains two independently installable Python packages: the memory core described here and an optional policy registry. The technical package names remain hermes-memory-core and hermes-policy-registry. The optional registry 0.2.0a2 also assesses versioned workflow effects with independent host verification; see packages and releases.
Français · API and service · Recovery contract · Contributing · Testing and reproducibility
Versioned memory for applications and agents that need to know which evidence a result depends on, whether it is still current, and what happens after a withdrawal or an old backup is restored.
Python 3.11+, SQLite with FTS5, standard library only. Linux is the qualified platform. No model, weights, account, external database, or persistent server is required. This is an alpha library; the repository contains synthetic examples and reusable code, not a private memory system or its data.
A focused identifier-validation change reduces instrumented runtime by a median 6.79% and CPU time by 6.77% across three new paired comparisons. The six cells retain the expected reads and revocation behavior. Workload, measurements and reproduction.
From this source distribution, in a fresh environment:
python3 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/hermes-memory-demo --directory /tmp/hermes-memory-exampleUse a new directory. Actor A registers two synthetic evidence sources and a dependent handoff. Actor B reopens the store, withdraws one source, and verifies that the dependent handoff is denied while the unrelated source remains readable. An old content backup is then restored against the retained current authority: it starts in quarantine and cannot resurrect withdrawn evidence after validation.
The output reports each checked invariant. It does not claim physical erasure, model unlearning, or protection when the store, authority and freshness witness are all rolled back together.
The optional structured renderer turns explicitly reviewed facts into finite French templates, preserves source spans and versions, and checks a word/citation contract. The admission boundary adds a host-reviewed dependency dossier, authority checks before preparation and handoff, useful notices, and explicit delivery outcomes.
python -m hermes_memory.admission_demoThis synthetic example covers a reviewed card, unknown/conflicting evidence, withdrawal, missing authority, a changed buffer, an unmet word limit, and an effect without acknowledgment. These synchronous APIs are opt-in. They do not extract facts from arbitrary briefs or verify semantic truth. A sink acknowledgment is not downstream consumption; authority and publication are not atomic. See the linked contracts before integrating a real authority or consumer.
from pathlib import Path
from hermes_memory import Authority, Memory
from hermes_memory.typed_memory import TypedMemory
root = Path("example-state")
root.mkdir()
authority = Authority.create(root / "authority.db", root / "witness.json")
memory = Memory.create(root / "content.db", authority)
typed = TypedMemory(memory, root / "search.db")
ref = typed.put("demo", "checklist", "Copper repair checklist.", {
"evidence_kind": "procedure", "preconditions": {"power_off": True}
})["ref"]
typed.sync("demo") # explicit, bounded index rebuild
result = typed.search("demo", "copper", conditions={"power_off": True},
max_context_chars=1000)
assert result["items"][0]["ref"] == refRefs include a workspace, stable artifact identity and immutable version. Updates use compare-and-swap. Derived records declare exact parent refs. Reads revalidate current versions and withdrawals; the search index is a disposable candidate projection, never an authority.
Typed envelopes support document, observation, hypothesis, procedure, task and feedback; explicit validity intervals, aliases and exact preconditions; FTS5 lexical candidates; a character budget; and coverage/exclusion details. A hypothesis remains a hypothesis. Declared confidence is not a learned quality score or a ranking weight.
The typed policy retains the R3 retrieval contract with optional exact-reference rendering. Its bounded synthetic comparison improved evidence selection but exceeded its registered relative latency gate. No production speed improvement, semantic search, graph inference, historical-version search, or automatic learning is claimed. Experimental R4 is not included.
Set render_source_references=True in TypedMemory.search to append each validated immutable ref to its complete text. The full text, JSON ref and separators share the character budget; an item that does not fit is excluded intact. Plain text remains the default.
hermes-memory provides initialization, core RPC, a synthetic demo, HTTP and MCP stdio. hermes-memory-typed provides explicit typed admission, synchronization, context and optional serving. See API.md for copyable local commands.
The Python server API adds make_server(..., typed_only=True) to expose only the authenticated typed POST routes; core /rpc, /validate and GET routes are refused. Configure Policy(render_source_references=True) and Client(..., render_source_references=True) together when using referenced contexts. These options bind a configured workspace and bearer token; they do not authenticate a person or voice. See API.md.
The typed HTTP routes and client are read-only; the optional combined server also exposes the privileged core /rpc API under the same token. It is intended for a trusted application boundary, not an untrusted multi-tenant deployment. Workspace names are logical partitions, not user ACLs. No public vector backend adapter is advertised; generic core projections retain exact refs but are not Qdrant or LanceDB integrations.
python -m pip install build
python -m build
python3 -m venv /tmp/hermes-memory-check
/tmp/hermes-memory-check/bin/python -m pip install dist/hermes_memory_core-0.3.0a5-py3-none-any.whl
SOURCE="$PWD"
cd /tmp
/tmp/hermes-memory-check/bin/python -m unittest discover -s "$SOURCE/tests" -v
/tmp/hermes-memory-check/bin/python "$SOURCE/benchmarks/run_benchmark.py"The test sources stay outside the installed package; imports resolve to the wheel. The current memory sources contain 166 public test methods; the optional policy registry has 49. Version 0.3.0a5 passed installed-wheel and rebuilt-source tests in two Linux environments: 215 distinct methods, 430 executions per environment. Qualification and checksums identify the exact released archives. Version 0.3.0a4 was qualified from installed wheels and rebuilt source distributions in two Linux environments. A private application's AST wiring test is deliberately absent and is not counted as public coverage. TESTING.md describes provenance and boundaries.
The benchmark uses 24 generated notes and reports observations, not a universal speed score. No corpus scan, model download, or network service is involved.
The optional synthetic LanceDB demonstration exercises explicit vector/text retrieval and current-version/withdrawal checks with predefined vectors. It uses separate optional dependencies; the default benchmark remains unchanged.
- A current external authority and retained freshness witness are required for safe recovery; keep them outside content-only snapshots.
- Missing dependencies and stale indexes are reported explicitly, so the caller can avoid using unvalidated evidence. Empty results are not a substitute for unavailable authority.
- Index rebuilding and admission are explicit and bounded. No automatic ingestion or historical corpus migration occurs.
- Context budgets count Python characters, not tokens. R3 can replay authority history per operation; the cost of that work depends on the journal length.
- Revocation controls future reads through this library. It cannot recall text already copied elsewhere.
- The application decides consent, retention, user permissions, trusted storage and backup policy.
MIT license. File selection and packaging transformations are recorded in PROVENANCE.json. The optional policy registry is a separate distribution; see PACKAGES.md. It does not activate policies or grant runtime permissions.
Each study defines its workload and the conclusions it supports. A condition outside that scope is untested by that study, rather than an observed failure. Answer-quality scores describe agent outcomes; software checks assess the memory contracts separately.
A pilot across eight histories follows evidence changes between sessions. Memory achieves 77/96 primary successes against 29/96 for versioned lexical retrieval, with nine unknown outcomes in each condition. Its 192 synthetic attempts and the two Codex readers' verdicts are provided with an offline verifier.
The confirmation study covers 100 distinct synthetic scenarios, with three repetitions for each model and condition: all 1,500 answers were delivered and all 3,000 AI judge responses completed. GPT-6 Luna succeeded on 298/300 answers with memory (99.33%), versus 29/300 without; GPT-6.1 Sol reached 300/300 versus 30/300. Luna’s primary gain was 89.67 percentage points, with a nominal 95% interval of 89–90 points and a one-sided 95% lower success bound of 98%. Lexical retrieval succeeded on 294/300: the 95% memory/lexical effect interval, −0.33 to +3.33 points, does not establish superiority.
The study page is the canonical account of methods, failures, limits and offline recalculation. These short, structured scenarios were assessed by two AI judges, without an external human quality audit. The earlier 500-task campaign and evaluator erratum, technical reliability and load results, and eight-task exploratory application pilot provide separate evidence; their counts and scope are not combined with this confirmation study.
The separate lifecycle comparison replays 100 fixed trajectories on three implementations in two Linux environments. Hermes and SQLite with retained authority both preserve all 751 valid reads and block all 389 forbidden reads per run; restoring old authority with old content exposes 82 withdrawn or superseded records. The main comparison is a tie on these guarantees, with complete synthetic observations available for inspection and reproduction.
The secondary efficiency analysis links all 1,500 historical answers to their reported usage. Luna with memory used 4.70% fewer tokens and 3.75% less estimated generation cost than lexical retrieval, with slightly higher p95 and inconclusive quality superiority. This is an observed footprint, not a matched-spend or general dominance claim; the analysis makes no new provider requests.
The artifact action study verifies CSV/JSON effects across three separate processes. Across 24 worlds drawn from 12 templates, Luna with memory passed 66/72 tasks versus 35/72 without memory, with one unavailable response in that latter arm; Sol passed 72/72 versus 36/72. Versioned lexical retrieval scored 67/72 and 72/72, so superiority over that baseline is not established. Synthetic observations, initial failures, calibration and the protocol amendment are retained with reproduction commands.
The core optimization study measures the same 1,000-source workload before and after a small serialization change. Instrumented workload time fell by 28.01% and 27.68% on two Linux hosts, with identical checked outcomes and storage size. Eight real process-kill trajectories also passed. These are single observations per host, not a production latency or general scaling guarantee.
The paired admission benchmark compares a source-admission checkpoint change with the previous core across three pairs of fresh processes. At 1,000 synthetic sources and 50 searches per run on common RAM storage, median paired reductions were 22.33% in instrumented elapsed time, 28.72% in ingestion time and 22.33% in CPU time. All six runs passed the same correctness checks. These are descriptive results from one Linux host, not a production or general scaling claim.
The incremental memory cycle separates the cost of loading 1,000 synthetic sources from the subsequent work: adding and reading ten sources, synchronizing, searching, then checking withdrawal and a valid control. The study compares the same two cores in three pairs of fresh processes; its report keeps setup and marginal costs separate, with the protocol, observations and limits available for inspection. The benchmark CLI is provided by this Git revision; the a4 release archives remain unchanged.
The learned-experience study executes A, extracts a lesson from its real outcome, then applies it to a different B task in a fresh process. Across 288 calls, Luna succeeded on 22/24 B tasks with the derived lesson, versus 13/24 with the complete trace and 7/24 without experience. Sol scored 24/24 with either the lesson or trace, versus 12/24 without experience. The files produced by all 192 B tasks were independently reopened and verified. The study reports construction overhead, failures and limits, with offline reproduction.
The real-agent integration report covers a memory on/off tie and reuse by a second agent, with targeted test results and the generated proposal's remaining issue.
The comparison with ECC Continuous Learning publishes all 128 outcomes from 32 cases, allowing up to three attempts on each new task. It evaluates the native Hermès integration alongside a local ECC adaptation, task history and a no-history condition. The predefined advantage criteria were not met. The public package supplies the reusable memory library.