EviCortex documentation
EviCortex is a pre-alpha, local-first Python research kernel for evidence-preserving, temporal memory in LLM applications. It stores exact source observations, derives rebuildable views, and compiles traceable evidence into a hard estimated-token context budget.
The project is testing a research hypothesis; it has not established that it is better than a tuned dense, hybrid, graph, agentic, or production RAG system. Start with the getting-started guide to run the implemented kernel.
Choose a path#
| Goal | Start here |
|---|---|
| Install EviCortex and run a temporal-memory example | Getting started |
| Understand evidence, claims, time, projections, and capsules | Core concepts |
| Look up public classes, methods, and provider options | API guide |
| Reproduce tests and research checkpoints | Benchmarking and reproducibility |
| Check current limitations, security boundaries, and common questions | FAQ and limitations |
Recommended learning path#
- Follow Getting started and inspect the returned
MemoryCapsule. - Read Core concepts, especially namespaces, temporal revisions, and the difference between exact evidence and derived claims.
- Use the API guide when integrating the embedded library.
- Read FAQ and limitations before evaluating EviCortex for real data or a multi-user application.
- Use Benchmarking and reproducibility before interpreting or publishing performance results.
Design and research record#
These documents describe the deeper design, evaluation contract, and retained results:
- Architecture and invariants
- Benchmark contract
- ADR 0001: local Python and SQLite kernel
- Prototype A result
- Prototype B semantic and extraction plan
- Prototype B diagnostic result
- Phase C pinned semantic evaluation
- Phase C semantic smoke result
- Phase C machine-readable smoke artifact
The result files are engineering checkpoints with named configurations and explicit claim boundaries. The synthetic suites are useful for regression testing, but they are not substitutes for official external benchmarks, a shared reader model, calibrated abstention, or statistically powered comparisons.
Current implementation boundary#
Implemented today:
- a Python 3.12 embedded library backed by SQLite and FTS5;
- immutable evidence records with provenance, occurrence time, and recording time;
- explicit versioned claims, current and historical valid-time recall, and conflict surfacing;
- lexical, entity, graph, temporal, and optional exact-semantic retrieval;
- deterministic context packing, stable evidence IDs, and retrieval traces;
- provider-neutral extraction, embedding, and reranking contracts;
- deterministic diagnostic providers and an optional pinned local Transformers adapter;
- integrity checks, deterministic index rebuilds, semantic repair, and scoped purge; and
- synthetic benchmark runners plus a strict LongMemEval-schema retrieval runner.
Not yet established or production-ready:
- authentication or authorization, encryption, a network service, or distributed storage;
- natural-language claim extraction supplied by EviCortex;
- approximate-nearest-neighbor retrieval at large scale;
- calibrated unsupported-query refusal or reader answer accuracy;
- full transaction-time (
known_at) queries; or - superiority over a strong RAG or memory system.
See FAQ and limitations for the operational consequences of these boundaries.