Memorex
A governed personal memory substrate for AI products.
Memorex gives assistant systems a policy-aware memory layer with provenance, consent, lifecycle state, user review, correction workflows, metrics, and auditable retrieval.
A memory layer designed for systems that must be inspected.
Memorex is not a chatbot UI. It is the substrate underneath assistants — separating observations, claims, accepted facts, memories, lessons, consent, and audit traces.
Provenance-first memory
Every accepted fact carries the chain of observations and claims it came from. No fact exists without a source.
Consent-aware retrieval
ConsentGrants compose with access policy before a memory can enter a context package. Policy decides — never score.
Lifecycle-governed facts
Claims, accepted facts, memories, and corrections move through explicit, auditable lifecycle states.
Review and correction
Identity-bearing claims require a subject-bound recorded review. Corrections supersede facts and only supersede source claims when no active fact still depends on them.
Advisory scoring, authoritative policy
Reasoning may rank candidates. Local runtime policy decides whether they are returned; a Capsulang adapter is future work.
Traceable state transitions
Every transition emits a hash-linked trace event, and receipt-gated transitions must reference the event they emit.
From observation to retrieval — every step is governed.
Memorex enforces a strict separation between what was observed, what was interpreted, what was accepted, and what may be returned.
A raw, attributable record of a signal entering the runtime — never an interpretation of what it means.
- Must carry a source identity and timing.
- Starts with an untrusted trust_status; sources cannot escalate themselves.
- No interpretation is recorded at this stage — only what was observed.
{ "source_type": "manual_note", "trust_status": "untrusted" }- Rejects observations without attributable provenance metadata.
- Rejects observations trying to create themselves as trusted.
Assistant interpretations are not treated as facts.
Identity claims are never silently promoted.
Restricted memories cannot bypass policy gates.
Consent grants compose with retrieval policy before context leaves the runtime.
Lessons are advisory and visible — not hidden filters.
Every state transition emits a trace event.
Receipt-gated transitions must link to the emitted trace event.
Every accepted fact has provenance.
Fourteen composable surfaces, one governed pipeline.
Each surface is a small, typed module you can adopt independently. They compose into a governed runtime with explicit policy, audit, and observability contracts.
Observation ingestion
Capture raw signals from clients with source identity, timing, and trust band.
Claim validation
Validate structural and semantic invariants before a claim is allowed to enter review.
Fact lifecycle
Accepted facts require accepted claim lineage before storage can create them.
Memory lifecycle
Active, archived, restricted. Restriction is policy state, not a search filter.
ConsentGrant lifecycle
Grant, expire, revoke. Retrieval resolves referenced grants together with access policy.
Review queue
Identity-bearing and high-trust claims surface for explicit decisions through a typed queue.
Correction workflow
Corrections supersede prior facts without overwriting history and preserve source claims still used by active facts.
Lesson advisory presentation
Lessons surface to operators as advisory signals — never silent filters.
Policy-gated retrieval
Retrieval keeps scoring advisory and emits compact trace spans for hot-path operation.
Claim retraction driver
User corrections and provenance failures can retract claims through a public trace-emitting workflow.
Trace-backed metrics
Aggregate policy decisions, transitions, blocked memories, review depth, and expired grants.
MemorexClient Protocol
Downstream products get a typed contract without this repo becoming the end-user assistant UI.
In-memory & SurrealDB adapters
Use the in-memory reference adapters locally. The experimental SurrealDB adapter needs deployment-specific schema, migration, and operational hardening before production use.
Static analysis & dep-free tests
Ruff, mypy, and unittest discovery run with zero runtime dependencies.
From zero to a governed retrieval.
Run the checked-in example to ingest with explicit consent, persist through the governed memory-write boundary, observe a fail-closed confirmation gate, retrieve an uncertain interpretation without promoting it to fact, and verify the emitted trace chains.
Install
The runtime is dependency-free. Until a release is published, install the current package from a source checkout.
# Memorex is not published to PyPI yet. Install from source:
git clone --recurse-submodules https://github.com/advatar/Memorex.git
cd Memorex
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -e .Run the verified example
The checked-in example ingests with explicit storage and claim-extraction consent, creates a proposed claim with real lineage, commits an uncertain MemoryObject through the governed write boundary, keeps it out of durable fact storage, blocks retrieval until a subject-bound confirmation receipt exists, and verifies its trace chains.
# This exact example is version-controlled and run by CI.
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src \
python3 examples/quickstart.py
# Expected output:
# governed memory-write trace events: 2
# blocked until confirmation: require_user_permission
# authorized uncertain interpretations: 1
# verified retrieval trace events: 3Inspect the trace chain
Every state transition emits a hash-linked trace event. Verify the chain and derive metrics from the trace store.
# Inspect every trace event the runtime emitted, in order,
# and verify the hash chain is intact.
from memorex.metrics import get_metrics
from memorex.trace import verify_trace_chain
events = trace_store.list_by_trace_id("trace_retrieval_quickstart_allowed")
for ev in events:
print(
f"{ev['timestamp']} "
f"{ev['operation']:24} "
f"{ev['next_state']:18} "
f"prev={str(ev['previous_event_hash'])[:8]}"
)
# The executable quickstart checks this same three-event lifecycle.
assert verify_trace_chain(events)
metrics = get_metrics(trace_store, "user_123")
print(metrics.transition_counts)
print(metrics.blocked_memory_count)A small surface area. Strong invariants behind it.
Entry points accept governed mappings and explicit storage adapters. State-changing workflows expose their policy, receipt, and trace evidence instead of hiding side effects.
Returns a context package only after access policy and any referenced consent grants resolve.
from memorex.retrieval import (
AuthenticatedRetrievalPrincipal,
retrieve_context_package,
)
principal = AuthenticatedRetrievalPrincipal(
principal_id="assistant_runtime",
agent_access_class="assistant",
)
package = retrieve_context_package(
{
"id": "retrieval_001",
"subject_user_id": "user_123",
"intent": "assistant_personalization",
"query_text": "reply timing",
},
memory_store=store,
authenticated_principal=principal,
trace_store=trace_store,
)Supersedes the prior fact without overwriting it; the source claim remains active when other facts still depend on it.
from memorex.correction import apply_fact_correction
result = apply_fact_correction(
correction,
semantic_graph_store=graph,
operational_store=store,
trace_store=trace_store,
)Moves grants through trace-emitting lifecycle transitions.
from memorex.consent import expire_consent_grants, grant_consent
grant_consent(
"consent_grant_001",
operational_store=store,
grant_event={
"decision": "grant",
"granted_by": "user_123",
"subject_user_id": "user_123",
"entity_id": "consent_grant_001",
"granted_at": "2026-05-12T11:01:00Z",
},
trace_store=trace_store,
)
expire_consent_grants(
store.list_consent_grants_by_user("user_123"),
operational_store=store,
trace_store=trace_store,
)Retracts a claim for user corrections or provenance failures.
from memorex.claims import retract_claim
retract_claim(
"claim_001",
operational_store=store,
reason="user corrected the claim",
user_correction={"reason": "user corrected it"},
trace_store=trace_store,
)Scans trace events into policy, transition, review, and consent counters.
from memorex.metrics import get_metrics
metrics = get_metrics(
trace_store,
"user_123",
since="2026-05-12T00:00:00Z",
)
print(metrics.policy_decision_counts)
print(metrics.review_queue_depth)Defines the typed adapter contract for downstream products.
from typing import Protocol
from memorex.api import MemorexClient
def mount_runtime(client: MemorexClient) -> None:
# Downstream HTTP/RPC adapters implement this contract.
client.retrieve_context_package(
{
"id": "retrieval_001",
"subject_user_id": "user_123",
"intent": "assistant_personalization",
}
)Runtime policy. Enforced, not advised.
The dependency-free local runtime policy is designed for a future Capsulang adapter; no Capsulang adapter or conformance suite is implemented yet. Reasoning may score only pre-authorized candidates, and runtime policy decides whether content may leave the runtime.
- P001No assistant inference as fact without approval/evidence
- P002No silent identity promotion
- P003No hidden lesson application
- P004/P010Retrieval score cannot override access or consent policy
- P005No external communication without approval
- P006No third-party biometric inference
- P007Preserve ambiguity
- P008Provenance required
- P009Corrections supersede, never overwrite
- P012Consent and user sovereignty checks
Fourteen modules. One clear separation of powers.
Advisory reasoning may score. Runtime policy decides.
The trace chain is the memory of the memory.
Current trace chains detect accidental mutation and reordering inside the same trust boundary. SurrealDB trace heads avoid full-stream scans; external-auditor-grade deployments add signing, anchoring, or immutable storage.
In-memory adapters
First-class adapters for tests and local runtime. Zero external dependencies.
SurrealDB adapters
Operational and trace stores backed by SurrealDB, with trace-head pointers for efficient hot-path writes.
Hash-linked trace chain
Trace events use deterministic hashes, previous-event links, and receipt linkage for gated transitions.
Auditor-grade extensions
Add signing, anchoring, or storage immutability for external-auditor-grade deployments.
Run runtime tests on a clean Python install.
The runtime and unittest suite are dependency-free. Ruff and mypy are provided by the documented development extra.
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src \
python3 -m unittest discover -s testspython3 -m pip install -e '.[dev]'
python3 -m ruff check .
python3 -m mypyQuestions engineers ask before adopting a memory layer.
Concrete answers about consent enforcement, provenance guarantees, review and correction workflows, and what the trace chain actually proves.
Build AI memory systems that can be inspected, corrected, and governed.
Adopt Memorex incrementally — start with the runtime API, swap storage adapters when you're ready, and keep every transition auditable.