The xysq Memory Engine:
self-improving context engineering.

The problem: memory that grows but doesn't get better

Most AI memory today accumulates. It doesn't improve.

The standard setup: wire a memory store to your agents, index everything, retrieve top-k. When retrieval is wrong, you add a correction and hope quality goes up over time.

We call this hope-based memory. The problem is you can't see it work. You can't tell if last month's corrections changed anything, and you can't point at a correction and say what it fixed. Meanwhile the store decays: contradictions and duplicates pile up, and a superseded fact keeps the same retrieval weight as its replacement.

What's been tried

These gaps are known, and there's real work against them:

• Vector stores + RAG. Index everything, retrieve by similarity. Simple and fast, but there's no notion of truth over time: a superseded fact and its replacement are just two similar chunks.
• Extraction-based memory layers (Mem0 and similar). Extract facts from conversations, dedupe, update. Better than raw chunks, but the updates are decided by a model you can't inspect: no verbatim ground truth underneath, and no way to see what a correction actually changed.
• Temporal knowledge graphs (Zep and similar). Track when facts become valid and invalid. This gets recency right, but edits still apply without deterministic checks, and a correction doesn't enumerate everything it touches.
• Self-managed agent memory (MemGPT/Letta and similar). The agent edits its own memory. Flexible, but whatever the model writes is the memory. No trust chain, no audit.

The gap that remains: all of this improved storage and extraction. None of it made improvement itself observable, attributable, or governed. Feedback is still a hint you throw in, not a transaction you can verify. That's the gap the engine closes.

If you ship AI to production, context quality is part of system quality. It needs real engineering, not hope.

What the engine is

The xysq Memory Engine is a self-improving context engineering engine. Raw AI work goes in: session transcripts from your AI tools, uploaded files. It gets distilled into a context graph. The graph improves in response to feedback, and you can see the change on the next query.

Deciding what an AI system sees is an engineering problem, and engineering problems need observability, attribution, and rollback. The engine supplies those. (The same graph, rendered for humans, is the knowledge graph you browse and share.)

Three ideas carry the design:

1. Two layers, one trust chain. Immutable verbatim logs at the bottom. A distilled context graph on top. The graph must cite the logs.
2. Targeted feedback, applied now. A correction is a structured event. It restructures the graph and retunes retrieval in one run.
3. The model proposes, code disposes. A model drafts every change. Deterministic code verifies and applies it. No invariant is enforced by a prompt.

Two layers, one trust chain

Every push (a session transcript, a file) lands first in the verbatim layer: an immutable log, stored byte-for-byte, indexed within seconds. Nothing downstream can edit it. That's what makes everything downstream checkable.

A background worker merges new content into the context graph: readable pages made of addressable blocks, updated within minutes of a push. Work per push scales with the new content, not with the size of your corpus. There is no global recompute.

Between the layers sits the fact ledger. Every fact carries recency (when it became valid, when it was superseded, by what) and lineage (verbatim quotes from the log, stated vs inferred, and a dependency chain, so superseding a premise flags the conclusions built on it). A fact in a page is a rendered ledger row. It only changes through a new ledger event.

Six families of deterministic gates run in code:

• Assembled diffs must equal the declared edits.
• New facts must quote the log verbatim, or they quarantine for review.
• Fact renderings are frozen outside ledger events.
• The changelog is composed by the server, not the model.
• Every fact edit maps to exactly one ledger event.
• Validators catch contradictions, orphans, and malformed structure.

Every change goes through a write-ahead log. A crash mid-apply replays deterministically, without re-calling the model.

Each graph lives in its own version-controlled vault. Every change is a commit you can diff.

One boundary, stated plainly: the edit trail is guaranteed by code. Semantic judgment (did the model link a fact to the right entity?) is audited, not guaranteed. Perfect recording of edits, not perfect memory.

Targeted feedback, visible improvement

The standard playbook says: keep sending feedback and retrieval gets better, eventually. We think one targeted correction should beat a hundred vague ones, and its effect should be visible immediately.

Here's what happens when you correct the engine. You say: "we deprecated the v2 endpoint in March; everything routes through v3 now." The correction becomes a supersession event in the ledger. In the same run, code closes the old fact, updates every page that hosts it, and tags the stale chunks so retrieval downweights them. The next query serves the corrected state. If contradictory facts surface together, the response flags the conflict instead of returning both.

Applied now. Visible on the next query. Attributable forever: the ledger records what changed, on what evidence, superseding what.

Feedback tunes two layers:

• Structural: how knowledge is organized. Pages split, duplicates merge, contradictions resolve, links rewire.
• Retrieval: what gets selected. Superseded content is downweighted, ranking prefers current truth, and selection instructions are versioned overlays you can revert.

Three loops feed those layers:

1. Human feedback. Corrections, reviews, edits. Highest authority. Text a human wrote is never changed without superseding evidence plus review.
2. Self feedback. Quarantine outcomes and merge audits today. Contradiction sweeps and a scheduled consistency check across graph, ledger, and index are rolling out.
3. Usage signals. What actually got used downstream tunes what gets selected next.

It learns your domain, not a benchmark

Generic memory optimizes for generic benchmarks. Your system runs on your vocabulary, your entities, your priorities.

Entities and aliases are first-class records, so internal names and acronyms resolve to one node instead of fragmenting. A new entity is a reviewable event, not a silent mint. The instructions that steer distillation and selection are per-user and per-team, grown from your feedback and usage.

Compounding, concretely: by month three, retrieval in your domain behaves differently than it did on day one, and you can read the diff of how. Every adaptation is a versioned text change, not a fine-tune you can't inspect.

Governance: every change is a diff you can read

The right question for a self-improving system isn't "how good is it?" but "what happens when it's wrong?" Answer: nothing changes silently, and a mistake becomes a review item, not a corrupted store.

• Provenance on every fact. Quote, source, timestamp, lineage. Inferred claims are labeled and need multiple citations.
• Code-owned history. Changelogs are composed by the server and byte-checked. The model can't edit its own trail.
• A review queue. New entities, new pages, quarantined claims, a page shrinking suspiciously, conflicts with human text. If the queue passes a ceiling, distillation pauses and the owner is notified.
• Recoverability. Every failure mode has a defined recovery path. Deleting an item scrubs the ledger, history, vectors, and archives.

Gates handle the mechanical part. Humans handle judgment calls, at a bounded, visible rate.

Ownership

The engine's output is plain markdown pages plus a ledger, in a vault owned by one user or team. Context this valuable shouldn't live in a proprietary blob.

Today: full isolation per vault, export anytime. The direction we're building, rolling out now: bring your own storage (the graph mirrored to a drive you control, readable in standard markdown tools) and private deployment inside your own boundary. This is stated direction, not a shipped guarantee.

What we are not claiming

• Not perfect memory. Perfect recording of edits; semantic judgment is audited and bounded.
• No benchmark numbers here. The engine ships with a measurement harness, and the numbers we publish will come from it.
• Not magic. Three loops, two layers, and gates that make every adjustment inspectable and revertable.

The short version

Context today accumulates and decays. The engine replaces hope with a mechanism: verbatim logs under a context graph, a ledger with recency and lineage, gates on every change, and feedback that lands now, where you can see it.

Bring a correction and watch what it changes.