Pre-alpha research kernel · v0.3.0a0
EviCortex is a local-first Python engine for long-running LLM applications. It preserves exact observations, derives temporal and associative views, then compiles only the evidence a query needs under a hard estimated-token budget.
A three-plane design
Flat chunk indexes often mix source storage, retrieval strategy, and prompt assembly. EviCortex gives each concern a distinct contract.
Source of truth
Append exact observations with a stable ID, content digest, namespace, provenance, occurrence time, and recording time.
Derived projections
Project evidence into episodic, lexical, semantic, temporal, entity, and graph views without promoting derivations to ground truth.
Query-time product
Filter by namespace before ranking, fuse retrieval channels, resolve temporal conflicts, diversify, and pack a bounded capsule.
Evidence, not adjectives
These are controlled local checkpoints. Each result is paired with the comparator, workload, and tradeoff that gives the number meaning.
40.6%fewer estimated context tokens
EviCortex retrieved every required source in the synthetic sweep and fixed the mechanical FTS5 chunk baseline’s update failure.
The baseline is lexical and mechanical—not dense, hybrid, or production RAG. Storage and median retrieval were materially higher.
Inspect the result34.6%fewer estimated prompt tokens
Supported-answer and temporal scores matched a metadata-aware hybrid using the same deterministic hashing projection.
Hashing is not semantic understanding. Both systems abstained correctly on only 1 of 3 unsupported probes.
Inspect the diagnostic199.0mean estimated context tokens
A pinned BGE encoder ran offline end to end. Both EviCortex and the hybrid retrieved all answerable gold sessions at rank 1.
This verifies wiring only. It is not official LongMemEval, has no reader, and is far too small for a quality claim.
Inspect the smoke testRun it locally
The deterministic core requires Python 3.12 and has no runtime dependencies outside the standard library.
# Clone and enter the repository
git clone https://github.com/Varun-SV/EviCortex.git
cd EviCortex
# Create a Python 3.12 environment
python -m venv .venv
# Activate it, then install the local package
python -m pip install -e .
python examples/quickstart.pyOptional dense-encoder support is isolated in the local-transformers extra.
from evicortex import ClaimInput, EviCortex
with EviCortex.open("memory.db") as memory:
memory.remember(
namespace="assistant/user-1",
content="Ada prefers the dark theme.",
source="conversation/42",
claims=[ClaimInput(
"user:ada", "prefers_theme", "dark"
)],
)
capsule = memory.recall(
namespace="assistant/user-1",
query="Which theme does Ada prefer?",
budget_tokens=300,
)
print(capsule.to_prompt())Prototype A is an embedded library. A host application must authenticate callers and authorize namespaces; the local SQLite file is not encrypted.
Documentation map
Start with the system contract, examine how comparisons are controlled, then inspect the retained results and their claim boundaries.
Open all documentationBuild on inspectable memory
EviCortex is open for researchers and builders who want memory claims to be falsifiable, reproducible, and linked back to evidence.