EviCortex GitHub

Open-source research kernel · pre-alpha

Remember everything. Pack only what is still true.

EviCortex is a local-first Python memory kernel for long-lived AI systems. It keeps every observation exactly as recorded, tracks which claims a newer one has replaced, and compiles a cited context capsule under a hard token budget.

Get started See it work

The problem

Old facts look just as relevant as new ones.

Question sent to memory“Which interface theme does Ada prefer?”

01 / A PREFERENCE CHANGES

In January, Ada picks light. In April, she switches to dark.

Assistants that run for months collect facts that change. Each update is just more text in the history.

  • 2026-01-02Ada prefers the light interface theme.
  • 2026-04-18Ada switched to the dark interface theme.
02 / CHUNK RETRIEVAL PACKS BOTH

Both chunks match the question, whatever the date.

The reader model has to guess which one is still true, and the outdated chunk spends budget the current one needed.

  • stalechunk 14 · Ada prefers the light interface theme.
  • currentchunk 61 · Ada switched to the dark interface theme.
03 / EVICORTEX PACKS WHAT IS TRUE

The newer claim supersedes the older one. Nothing is deleted.

Both observations stay in the evidence ledger. Only the current fact is packed, with a stable evidence ID you can expand.

  • packeduser:ada prefers_theme = "dark" · valid from 2026-04-18
  • ledgeruser:ada prefers_theme = "light"
04 / ASK ABOUT THE PAST

Set as_of and the capsule shows what was true then.

History is a query, not a deletion. On 1 Feb 2026 the light theme was the valid claim, and that is what gets packed.

  • packeduser:ada prefers_theme = "light" · valid 2026-01-02 → 2026-04-18
  • not yet validuser:ada prefers_theme = "dark"

Illustration built from examples/quickstart.py. Behaviour, not a benchmark.

How it works

Three planes. One bounded capsule.

EviCortex separates the evidence it keeps from the views it uses to find that evidence. Views can be wrong or rebuilt. The evidence stays put.

01

Evidence ledger

Genome

Append-only observations with source, SHA-256 digest, namespace, and both occurrence and recording time. The lossless source of truth.

02

Memory indexes

Engram

Rebuildable claim, lexical, entity, graph, temporal and optional semantic views. A correction creates a revision instead of erasing old evidence.

03

Context compiler

Transcript

Query-time ranking, temporal filtering, conflict surfacing and packing under a strict estimated-token budget, with stable IDs you can expand later.

The recall pipeline

Fly through a recall.

Seven gates between a question and a capsule. Watch the rose (superseded) evidence drop out at the temporal filter, and the stream narrow at the packer.

Interim results · cutoff 25 Oct 2026

Stale evidence stays out. Clean coverage at 4k.

0.00%

Stale-reference inclusion on knowledge updates

Across 200 knowledge-update queries at a 512-token budget, no EviCortex capsule included a superseded source. Fixed-chunk FTS and Hybrid RAG did in 100% of them.

99.27%

All gold and no forbidden IDs at 4,000 tokens

On the matched answerable cohort (n = 1,921), EviCortex packed every gold source and no forbidden one in 99.27% of queries. Both chunk baselines reached 89.59%.

These are source-ID retrieval proxies, not answer accuracy. No reader model was run. Each number reports which evidence IDs ended up inside the packed context.

Mean source-ID recall by budget

Matched answerable cohort, n = 1,921

  • EviCortex
  • FTS and Hybrid RAG (identical)
Mean source-ID recall by token budget EviCortex: 71.73% at 512, 69.99% at 1000, 69.73% at 2000, 99.27% at 4000, 100% at 8000. Fixed-chunk FTS and Hybrid RAG: 100% at every budget. Active research: small-budget recall 100%75%50%25%0% 5121,0002,0004,0008,000Context budget (estimated tokens) 71.73%69.99%69.73%99.27%

All gold and no forbidden IDs

Share of queries whose context held every gold source and no forbidden one

  • EviCortex
  • FTS
  • Hybrid RAG
All gold and no forbidden source IDs, at 512 and 4,000 tokens At 512 tokens: EviCortex 65.12%, FTS 89.59%, Hybrid 89.59%. At 4,000 tokens: EviCortex 99.27%, FTS 89.59%, Hybrid 89.59%. 100%75%50%25%0% 65.1289.5989.5999.2789.5989.59 512 tokens4,000 tokens

Stale-reference inclusion on knowledge-update queries

n = 200, budget 512 tokens. Lower is better.

Show all numbers as a table
Metric and budgetEviCortexFTSHybrid RAG
Mean source-ID recall, 51271.73%100%100%
Mean source-ID recall, 1,00069.99%100%100%
Mean source-ID recall, 2,00069.73%100%100%
Mean source-ID recall, 4,00099.27%100%100%
Mean source-ID recall, 8,000100%100%100%
All gold, no forbidden, 51265.12%89.59%89.59%
All gold, no forbidden, 4,00099.27%89.59%89.59%
Stale-reference inclusion, 512 (n = 200)0.00%100%100%

Small budgets are still a weak spot

At 512 to 2,000 tokens EviCortex recovers about 70–72% of gold source IDs, while both chunk baselines recover all of them. That gap is where current research effort goes.

Methodology

How these numbers were measured.

Corpus
Authored evaluation corpus, not the official LongMemEval-S artifact
Cohort
Matched answerable cohort, n = 1,921 queries
Updates
Knowledge-update queries, n = 200, at a 512-token budget
Mode
Retrieval only. No reader model generated an answer
Budgets
512, 1,000, 2,000, 4,000 and 8,000 estimated tokens
Tokens
One token per three UTF-8 bytes, not a model tokenizer
Baselines
Fixed-chunk full-text search and a Hybrid RAG comparator
Mean source-ID recall

The average share of a query’s gold source IDs present in the packed context.

All gold and no forbidden IDs

The share of queries whose context holds every gold source and none marked forbidden.

Stale-reference inclusion

On knowledge-update queries, the share whose context includes a source a later update superseded.

Not measured here
  • Answer accuracy with a shared reader model
  • The official LongMemEval-S dataset
  • Any comparison with Mem0, Graphiti or HippoRAG 2

Quickstart

Run it on your machine.

  • Python3.12 or later
  • StorageSQLite with FTS5, included in standard CPython builds
  • Runtime depsNone beyond the standard library
  • Packageevicortex-research, imported as evicortex
  • LicenceMIT
git clone https://github.com/Varun-SV/EviCortex.git
cd EviCortex
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python examples/quickstart.py

Roadmap

Next: small-budget recall.

The baselines fit all gold evidence into 512 tokens, so the gap comes from selection and serialization, not from the budget itself.

  1. Shipped

    Prototype A kernel

    Evidence ledger, versioned claims, valid-time recall, conflict surfacing and hard-budget packing on SQLite and FTS5.

  2. Shipped

    Extraction and embedding projections

    Audited claim-extraction boundary with exact source spans, durable semantic profiles and repair.

  3. Shipped

    Pinned semantic path

    Offline dense-encoder adapter, reranker seam and a strict LongMemEval-schema retrieval runner.

  4. In progress

    Improving small-budget recall

    Close the 512–2,000 token gap without giving back the 0% stale-reference result.

    1. Phase 1 · no modelsPer-stage miss audit and a fine budget sweep. A budget-monotone knapsack packer. A compact provenance legend. Temporal annotate-then-guard, so 0% stale holds by construction.
    2. Phase 2 · local retrievalA dense or learned-sparse channel fused with RRF, plus cross-encoder reranking for paraphrase- and distractor-heavy histories.
    3. Phase 3 · optional +LLMIngest-time proposition keys, multi-hop expansion over valid edges, and conditional query rewriting, reported as separate variants.
  5. Planned

    Official LongMemEval-S evaluation

    Byte-verified dataset, preregistered configuration, and no-memory, full-history and oracle controls.

  6. Planned

    Shared reader and answer accuracy

    Move from retrieval proxies to answers, with exact reader-tokenizer accounting and calibrated abstention.

Documentation

Go deeper. Every guide is here.

01 · START

Getting started

Install the kernel and inspect your first MemoryCapsule.

 02 · LEARN

Core concepts

Evidence, claims, time, projections, namespaces and capsules.

 03 · BUILD

API guide

Public classes, methods and provider options.

 04 · DESIGN

Architecture

The three planes and the invariants that hold them together.

 05 · MEASURE

Benchmarking

Reproduce tests and research checkpoints.

 06 · ASK

FAQ and limitations

Security boundaries, limits and common questions.

Paper

The paper is in preparation.

A write-up of the design, the evaluation contract and the full results. It will report final numbers, not the interim ones above.

Read the benchmark contract