| AIGC |
|
|---|
Local-first memory and evidence-gated learning for long-running AI agents.
Durable context · Scoped hybrid recall · Reviewed knowledge · Replay, promotion and rollback
Quick start · Why eimemory · Integrations · Validation status · Docs
eimemory preserves decisions, preferences, corrections, incidents, outcomes,
knowledge and capability evidence across agent sessions. It retrieves context
through CLI, Python, authenticated RPC and host adapters, then uses evaluation
and governance to decide whether a proposed improvement can advance.
Latest reported deployment and nightly: successful on 1.14.72 / 612dc458.
Formal recall remains 0/3 and unaccepted. Deployment receipt
rec_fba7350aa0b4 records successful installation, binding refresh and health
checks on October 13, 2026 (Asia/Shanghai), with active RPC and matching current
and target releases. Nightly ref_d6eb0f6e9c6f ran 02:15:05–02:23:40 and
exited 0 with no failed steps.
Controlled memory evaluation passed 7 of 8 cases. The failed known-item case returned no final records. Its completed trace shows an available SQLite source without fallback; the target was absent from the complete, untruncated 14-candidate source-returned window and subsequent candidate stages. This excludes selector rejection of that target in this run. It does not establish index absence: query generation, source matching and source-internal filtering remain unresolved. Generated checks stay outside formal production evidence. Collection created five cases and found 164 existing cases, with no collection skips; all five new cases had empty candidates. The review summary records 365 reviews, no pending/open reviews and zero formally accepted cases. Nine evolution results each have zero candidate hypotheses; an applicable knowledge link for the current gap revision is still missing. See team acceptance.
One participant's small live Hermes readback on 1.14.69 reported healthy queuing, retained source statements about a state change and an older state, but two empty durable-memory queries. Exact source, scope, full commit and stage evidence were not supplied; this cannot identify a particular defect or certify team recall.
Version 1.14.71 repairs mixed-input filtering, USER/ASSISTANT parsing, current-source binding and event-time ordering in memory extraction. New reference-only diagnostics trace the actual admission/model/write path. The supplied execution receipts do not verify recovery of those two participant queries, factual truth of model output or team recall quality. The 1.14.70 inventory, provider and controlled-retrieval contracts remain available; their earlier source validation is separate from this production readback. Policy v5 still requires three qualifying cases and trusted labels within the existing exact dataset scope, with unchanged quality and authorization checks. See the receipt-based acceptance status.
Version 1.14.72 adds a private native trace for one controlled target, retaining observed stage presence and the target's actual rejection reasons. Missing measurements remain unknown. It preserves the original query, case ID, expected record, selector, grounding and thresholds, without extra retrieval reads or candidate injection. The supplied 1.14.72 readback verifies the trace on that controlled failure, without certifying its recovery or formal quality.
Mainline 1.14.73 aligns controlled positive-target eligibility with the existing recall source policy. Capture-rejected records, shared raw episodes and default evidence-only records cannot become positive known-item expectations; normal recallable L1 episodic memories remain eligible. Generation records policy skips; on a new validation, existing ineligible cases are non-evaluable while historical outcomes remain unchanged. Eligibility does not depend on a recall failure or grounding score, and an all-empty dataset cannot pass. A bounded native SQLite trace observes actual source matching, scoring and cap windows without extra SQL, reads or candidate injection. It does not certify index absence, the cause/recovery of the older miss or formal quality. No 1.14.73 production acceptance has been supplied. See controlled eligibility and source traces.
- Durable memory. JSONL records, SQLite projections, provenance and recovery tools preserve operational context across sessions.
- Scoped hybrid recall. Lexical, graph, quality and recency signals select task-relevant context. Optional semantic retrieval requires an external OpenAI-compatible embedding API; without it, lexical and graph retrieval remain available. Optional semantic admission adds reranking, no-evidence decisions and separate positive/negative evaluation.
- Reviewed knowledge. Paper and URL intake retain raw artifacts, canonical text and parser manifests. Compiled claims and pages retain their provenance; malformed or unverifiable sources stay blocked.
- Bounded learning. Scheduled analysis turns weak signals and failures into hypotheses and candidate improvements. Isolated evaluation, evidence-bound replay, machine policy, observation and rollback govern promotion.
- Explicit evidence. Capability maturity is assessed by exact revision, provider binding, owner scope and deployed identity. Process health, smoke, memory benchmarks and formal business acceptance remain separate results.
The core is framework-agnostic and has no mandatory third-party Python runtime dependencies. Optional PDF parsing, PostgreSQL, embedding services, model review and host adapters add their own dependencies, costs and data boundaries.
Python 3.11+ is required. Install the source checkout in an isolated environment:
git clone https://github.com/darrowz/eimemory.git
cd eimemory
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
eimemory init
eimemory ingest "Be concise and direct" --title "Communication style"
eimemory recall "How should this agent reply?"
eimemory learn cycle --dry-run
eimemory doctor --jsonFor a reproducible install, check out a reviewed commit before installing. Production uses immutable releases, rather than editable source installs. The Quick Start explains store paths, RPC and evaluation; the FAQ covers common questions.
from eimemory import Runtime
runtime = Runtime.create(root="./data")
runtime.memory.ingest(
text="Deploy only after tests and health checks pass.",
title="Release rule",
memory_type="fact",
scope={"agent_id": "main", "workspace_id": "default"},
)
bundle = runtime.memory.recall(
query="What is the release rule?",
scope={"agent_id": "main", "workspace_id": "default"},
)Use the public Runtime, RPC or adapter contracts. Keep runtime data and
credentials outside the source checkout.
CLI / Python Runtime / authenticated RPC / host adapter
-> ingest, recall, verified outcome
-> durable records + indexes + memory graph
-> scoped retrieval and evidence assembly
-> hypotheses + trusted evaluation + governance
-> gated promotion + observation + ledger
-> retain or rollback
| Plane | Main packages | Responsibility |
|---|---|---|
| Data | models, storage, raw, knowledge |
Records, artifacts, provenance, indexes and compiled knowledge |
| Recall | recall, retrieval, embeddings, scoring |
Candidate generation, filtering, ranking and diagnostics |
| Control | capabilities, experience, evaluation, governance |
Capability contracts, evidence, replay, promotion and rollback |
| Integration | api, adapters, ei_bridge, cli, ops |
Public APIs, host hooks, RPC and operations |
See Architecture and the Module map for ownership and execution boundaries.
Host adapters share the agent.runtime.v1 lifecycle contract: recall, durable
capture, verified outcome and status. Authority is per_channel; Codex and
Hermes use separate channel scopes such as embodied::channel::codex and
embodied::channel::hermes. There is no implicit cross-channel recall.
| Host | Integration | Guide |
|---|---|---|
| Codex | Session hooks and four MCP tools | Plugin |
| Hermes Agent | Native memory provider and host hook bridge | Provider, hooks |
| OpenClaw | Optional external plugin with eight lifecycle hooks | Bridge |
| eibrain / custom agents | Public Python facade and bounded HTTP/RPC | Operations, architecture |
OpenClaw is optional. The immutable installer accepts
EIMEMORY_OPENCLAW_ADAPTER=auto|enabled|disabled (default auto); an enabled but
incomplete integration fails closed. See the systemd guide.
Remote clients configure EIMEMORY_RPC_URL and EIMEMORY_RPC_TOKEN outside
tracked files. Hook failures are bounded and fail-open for host availability;
persistence, trusted outcomes and promotion remain fail-closed for trust decisions.
Task attestation requires a separate host producer boundary.
eimemory serve-eibrain-rpc --host 127.0.0.1 --port 8091
curl -fsS http://127.0.0.1:8091/healthHealth is unauthenticated; non-health RPC methods require the configured auth and attestation policy. See the RPC security runbook.
One production flow owns learning state:
scoped outcomes + reviewed knowledge + adapter advertisements
-> capability registry + sealed evaluation catalog
-> hypotheses + replay + isolated evaluation
-> autonomous_learning + promotion_manager
-> observation + reward + ledger + rollback
-> readiness assessment
- Executable evaluators come from trusted installed entry points. JSON, YAML, database records and advertisements cannot register evaluation code.
- A missing catalog, ambiguous hypothesis, absent binding or incomplete evidence remains a blocking gap.
- Code patches require exact repository identity, allowed files, digests and focused verification. Commit and production deployment default to off and require separate deployment-controlled machine policies and receipts.
- Learning cannot grant authority for spending, external sends, credentials, private-data export or irreversible deletion.
- L5 v3 tracks loop maturity, capability readiness, adapter readiness and deployment assurance separately. Historical profile readiness does not certify a different release or current business recall quality.
Controlled known-item generation reuses the existing source-policy rules before forming a positive expectation. Capture-rejected records and raw/default evidence-only material stay excluded; normal L1 episodic memories are retained. Existing controlled cases are revalidated, so an ineligible target becomes non-evaluable rather than a pass. The dataset is not selected by its retrieval outcome, and an empty eligible set does not pass. The new SQLite source trace observes existing source-internal windows and target-specific branches without a target lookup, new query/read/model call or change to search ordering, limits, selector, grounding or quality thresholds. An absent target is absent from that observed SQL window; index absence or rejection by a specific SQL predicate cannot be inferred. The latest 1.14.72 evidence and earlier misses remain unchanged. See native source diagnostics.
Controlled known-item checks can observe one exact target through the native retrieval path. This private trace binds to one engine, source, scope and query, isolates nested/concurrent recalls, and records missing measurements explicitly. Query-generation diagnostics retain only the source field, length and truncation, without query text. Failed-case summaries retain the new trace for subsequent runs. The change adds no search, record read or candidate and leaves the query, case ID, expectation, selector, grounding and acceptance thresholds unchanged. The 1.14.71 report cannot acquire these missing historical target measurements; an isolated synthetic reproduction cannot establish its real query type or target membership. See controlled evaluation.
Mixed input with an independent statement followed by a question can reach the existing extractor model. An empty formatted USER section no longer absorbs an ASSISTANT line, and an embedded USER quotation cannot create a user turn. Whole-input secrets/automation checks, size limits and output constraints remain in force. Source reloads use the current persisted conversation material rather than stale caller text; state writes use an atomic source-time guard. That guard covers already established same-key or explicit update-target relationships; it does not merge every paraphrased state or correct every assistant conclusion.
New extraction diagnostics bind references and material digests to actual input,
model, filter and store outcomes. They neither certify every model-generated
fact nor fill missing historical diagnostics. Existing NoMemory outcomes are
not bulk replayed or relabelled. See
extraction provenance.
Knowledge inventory review now advances through bounded persistent pages instead of treating the first fixed window as the whole corpus. Applicability remains blocked until the complete scan supports one unambiguous eligible source. Provider failures receive safe diagnostic categories, while controlled known-item misses retain bounded retrieval-stage metadata. These diagnostics do not change ranking or establish the cause of the reported 1.14.69 miss. See inventory progress and controlled evaluation.
A successfully generated replay with no retrieval cases can use existing, authorized records for a controlled baseline when no configured dataset is selected. It exercises the real runtime recall path and revalidates source identity around retrieval. Configured input errors and unconfirmed replay success cannot activate fallback. A controlled pass remains outside natural production labels, independent memory acceptance and correct no-answer evidence. See controlled memory checks.
Missing knowledge links can receive a tool-free review through the installed Hermes runtime. Exact capability revisions, approved paper-backed knowledge, canonical quotations and source trust bind each applicability receipt; changed or revoked evidence invalidates it. Missing transport, evidence or unambiguous applicability remains blocked. See knowledge-gap review.
The official Hermes v2 route can build a known-gap maintenance proposal under the intersection of registered candidate bounds and a trusted machine policy. Independent suite evidence, provider attestation, isolated verification and the existing transaction owner govern effects and recovery. Known or user-reported maintenance cannot certify autonomous discovery or product completion. The 1.14.72 readback reports successful deployment and nightly execution, but nine evolution results still have zero candidates and no successful maintenance transaction is supplied. See Hermes maintenance authority.
Nightly diagnostics retain production_recall_collection with actual
new/existing counts, skips and up to 50 new pending/capture references, preferring
nonempty new cases. Only those exact IDs are joined to this run's review results.
Missing, ambiguous, reused and truncated references remain explicit; signals
not yet checked remain unknown. Semantic observations have separate counters.
See the collection contract.
Nightly failure reasons now include up to five native review-receipt/pending-case ID pairs per reason. A rare reason retains its own window even when common failures dominate. Missing references and truncated projections remain explicit; no query or memory body is copied. See review reference diagnostics.
New proactive decisions persist retrieval_diagnostics.session_dedupe with
removed record/source IDs, prior decision/citation references, observed state
and timestamps, and the deduplication basis. Reads share one SQLite snapshot.
Up to 64 witnesses are retained; total counts and truncation remain explicit.
An in-flight reservation is distinguished from prior injection or host feedback.
These diagnostics do not certify actual use, recall quality or a correct
no-answer, and do not add historical items to the current evaluation candidates.
See the diagnostic contract.
Authenticated health uses bounded, runtime-local storage and retrieval snapshots. A failed storage probe refuses readiness; optional retrieval timeout marks the source unavailable. Repeated requests reuse one in-flight reader, and expired healthy snapshots do not certify blocked refreshes. Authenticated liveness skips these readers and cannot substitute for deployment health. The operator's subsequent 1.14.66 readback reports deployment and nightly execution success; business evidence remains insufficient.
Policy production_recall_gate_policy.v5 lowers the minimum qualifying
case and label counts from 15 to 3, as explicitly requested by the operator.
It keeps trusted labels, release authorization, exact scope/source boundaries,
ranking, latency, resource, isolation and noninferiority checks. Historical
v4/v3/v2 policy payloads and digests keep their original 15-case/15-label floors;
older receipts cannot become accepted under the new policy by changing a count.
The reported 1.14.72 execution does not certify business recall quality. Existing memory can supply
controlled positive targets and companion checks; generated questions remain
controlled acceptance, outside natural production gold. See
using existing memory.
Digest/synthesis pages now use their full content, date and evidence identity for deduplication. A shared summary prefix no longer merges different daily aggregates or replaces a digest with a topic page. An isolated native smoke reproduces the earlier loss and retains the dated target after this repair, using the same query and expected ID. Exact duplicate collapse, source quotas and ordinary-query digest suppression remain in place.
Persisted diagnostic recall reports now retain expected record IDs alongside returned IDs, and explicit error-rate numerator/denominator counts. Query text, titles and memory bodies remain excluded. These fields help trace a failed known-item case without changing the metric or the ≤0.05 error-rate threshold. The historical 1.14.63 nightly reports smoke 10/10. The subsequent 1.14.66 execution succeeded, but formal business evidence remains insufficient.
Nightly summaries now preserve the fixed review failure codes for capture authority, missing original queries, low-signal features, unavailable candidates and semantic input failures. A versioned diagnostic catalog replaces the incomplete reason list. Unknown text stays redacted; oversized reason maps report truncation. This changes diagnosis, not review eligibility or quality gates.
Automatic production-query review now records a durable pass or fail for each scanned case. Insufficient signals, unavailable semantic review or disabled approval produce a completed non-passing conclusion with reasons. They do not create trusted labels. Original captures remain active, and later evidence can trigger a new review; repeating unchanged evidence reuses the same receipt.
Semantic review and research review share Hermes runtime discovery, including relocated launchers and console installations. Semantic review retains its tool-free, read-only child process. Nightly receipts preserve review conclusion counts/reasons, memory dataset diagnostics and reported hypothesis counts; missing fields remain unknown.
Research review now automatically discovers the service user's installed Hermes
runtime and reads its current provider, model and credential configuration.
It supports installation-bound launchers, Python console installs and legacy
source virtual environments without a fixed host path or model. Explicit review
commands remain available. SDK responses must identify the actual model, and
failed or tool-calling responses remain unavailable.
The requested model selection is gpt-6.1-sol with low reasoning; the bridge
reads it from the active Hermes profile and delegates reasoning wire parameters
to the installed provider adapter.
Deployment tests isolate the service account's OS home and system PATH. They separately require rejection without a service Hermes installation and discovery of an installed runtime with its current configuration, even when the deployment controller uses a different HOME or route. Changing only the test process's HOME does not isolate the account lookup used by deployment preflight.
Earlier repairs add durable research-review diagnostics and check managed review configuration before switching releases. They also include configured model review, strict review validation, separate catalog and retrieval evaluation, persisted not-run memory receipts, and exact binding diagnostics with consistent time cutoffs. Package and Codex/Hermes plugin versions are aligned.
The operator reports accepted deployment, healthy current services and successful
nightly execution for 1.14.63 / 4fbcbbc9. Smoke is 10/10; formal recall
quality and capability evolution remain unaccepted. These results belong to
that exact deployed commit. See 1.14.63 changes and
workflow repair details.
The latest readback is 1.14.72, full commit
612dc458322eb60f1631b4605b0a30eb8a517e99: deployment acceptance passed
(rec_fba7350aa0b4), and nightly ref_d6eb0f6e9c6f exited 0 without failed
steps. Controlled checks passed seven of eight cases. The empty known-item case's
target was absent from the complete source-returned window of 14 candidates and
subsequent candidate stages. It therefore did not enter the selector in this run;
the cause before source return remains unconfirmed. Five new captures have empty
candidates; 365 reviews have no pending/open work and 0/3 formally accepted
cases. Nine evolution results have zero candidates and lack an applicable
current-revision knowledge link. Participant-level recovery, formal business
quality and a successful evolution transaction remain unverified. Earlier
1.14.71 and 1.14.69 outcomes retain their own run identity, including the older
failure and historical off-topic references in
the receipt history.
An earlier operator-supplied persisted-receipt readback covers 1.14.63,
full commit 4fbcbbc99e228c753c2e0e255b7bad264a98c01a. Deployment completed on
October 11, 2026 at 12:09:26; nightly ran 12:09:26–12:17:36 (reported local
times; receipt timezone field not supplied).
Nightly produced 5,981, promoted 10 and rolled back 54. At that readback, the RPC process,
storage and readiness are reported healthy. References: deployment association
rec_c37c15ee113e, nightly ref_840ade0e6fbf, quality ref_6ae80df64e32.
The operator only read existing receipts, without a rerun or production change.
The documentation publisher has not independently queried production.
| Check | Reported result | Meaning |
|---|---|---|
| Deployment and current services | ok=true; install, binding refresh and health exits 0; live path matches receipt |
Deployment receipt acceptance passed; RPC/storage/readiness healthy |
| Nightly execution | Exit 0, execution_ok=true, no failed steps |
The preceding smoke violation did not recur; evidence insufficiency remains a non-actionable execution wait |
| Known-item smoke | 10/10, 0 failed; error rate 0.00, hit@1/hit@5 1.00 | Fixed known items are retrievable; natural-query quality is not certified |
| Team recall in actual Feishu conversations | Unverified | Each participant needs verified session identity, natural questions, no-answer near neighbors, permission checks and source readback |
| Automatic recall-label reviews | 321 reviewed, 0 passed, 0 pending | Reviews concluded; no accepted cases produced |
| Formal recall quality | Not accepted: gate_ok=false, recall_quality_evidence_incomplete, 0/15 cases |
Policy v4 requires 15 cases / 15 labels overall; coverage is limited to observed dataset hosts |
| Memory benchmark | Not evaluated: 0 retrieval cases, memory_eval_dataset_empty |
No memory benchmark ran; current dataset source was not supplied |
| Dynamic evolution | 9 results, each with 0 candidate hypotheses | Producer lacks an applicable knowledge link: no_applicable_knowledge_link_for_gap_revision |
These are historical production checks for 1.14.63. The new 1.14.64 minimum is 3 cases / 3 labels; it does not rewrite the reported denominator or produce new accepted cases. Team conversation checks remain unverified.
The earlier 1.14.62 durable summary confirmed the classification repair:
pending_capture_boundary_invalid 10, pending_capture_decision_missing
186, semantic_judgment_not_delivered 6. These three codes are preserved
directly. The last count was 5 in the earlier 1.14.61 run and 6 in 1.14.62;
current 1.14.63 reason counts were not supplied.
Reason occurrences can overlap and do not establish the cause of the smoke miss.
That run's failed target digest_bc2b3a1308f3d795 returned a topic and another digest,
matched neither, and had smoke noise 1.0. Operator comparison confirms the two
digests have different dates (October 10 and 11), identical 256-source sets and
identical summary prefixes. The local collision repair matches that record
shape; the actual failed run's stage trace was not supplied, so the loss at
deduplication is not independently confirmed for that historical execution.
The later 1.14.63 receipt reports zero smoke failures. A per-case identity
comparison or historical stage trace was not supplied, so it cannot establish
which previous case was rerun or prove the historical loss stage.
The earlier 1.14.57 / eab88240 smoke passed 10/10, with hit@1, hit@5 and
MRR 1.00 and P95 340.8 ms. Its noise 0.80 and precision@3 0.333 remain
historical smoke observations. The 1.14.62 error-rate violation was a separate
measured failure; the historical 1.14.63 smoke reports 0.00. Formal standards remain noise ≤0.40 and
precision@3 ≥0.60; completed failed reviews do not count as accepted labels.
The intervening 1.14.58 / 534bb2f0 nightly failed at research review
(ref_4cc83efb2f5d). Separate detailed-record readback established
research_review_llm_unconfigured; its durable summary omitted per-record
errors. That historical failure does not describe the latest execution result.
Mainline 1.14.59 adds bounded review failure reasons to durable nightly receipts, including command/bridge failures and review validation errors, and blocks managed deployment before switching when the durable review route is missing or invalid. Mainline 1.14.60 adds automatic Hermes review routing and configuration discovery to deployment preflight. These changes keep all formal quality gates. Version 1.14.61 completes non-passing automatic reviews and shares runtime discovery with the semantic judge. Version 1.14.62 expands safe reason diagnostics, confirmed in the earlier operator readback. Version 1.14.63 repairs digest identity collisions and preserves expected IDs/error-rate counts. Deployment, nightly and smoke have now passed their reported checks; formal business acceptance remains open. The 1.14.58 repairs cover model-command routing, memory/catalog separation, persisted not-run evidence and binding diagnostics. No new production acceptance or relaxed threshold is implied by these package changes. See acceptance status and remaining work.
Install pytest separately and run the suites affected by the change. Then:
python -m compileall -q eimemory
git diff --checkRelease verification and production acceptance are separate checks. See Contributing. Production installation uses an exact commit:
deploy/install_immutable_release.sh <full-40-character-commit>Verify the current-release symlink, RPC identity, managed services and persisted acceptance evidence after installation. Health or a systemd exit code alone cannot close the recall gate.
| Document | Contents |
|---|---|
| Documentation index | Guides by task and historical evidence boundaries |
| Quick Start | Install, ingest, recall and local diagnostics |
| FAQ | Configuration, integrations and readiness questions |
| Acceptance status | Latest reported receipts, unchanged standards and remaining work |
| Architecture / Module map | Data flow, public surfaces and ownership |
| Evaluation | Smoke, memory benchmarks, catalogs and formal acceptance |
| Deployment / systemd templates | Immutable releases, services and recovery |
| Operations | Channel setup, security and live verification |
| Comparison | Choosing and combining memory approaches |
| L5 v3 architecture | Readiness axes and maturity contracts |
| Changelog | Released behavior and historical changes |
Dated audit and plan documents preserve their original evidence. Read them as historical records; use current release-bound receipts for acceptance.
Maintainer: darrowz
Email: shelinedouville@gmail.com
MIT.
AI生成