Persistent Memory for AI Agents

Summary

Persistent Memory is a Python library for storing information used by AI agents, tracing it to its sources and excluding corrected or withdrawn evidence. It combines versioned memory with a separate policy registry. The MIT-licensed alpha runs on Linux without a model or external database.

Public results

Keep the thread across sessions
Retrieve useful information when a task resumes, taking account of corrections and changes since the previous session.
Across eight synthetic histories, memory achieves 77 successes out of 96, compared with 29/96 for a lexical baseline with validity checks. The counts include nine unknown outcomes per configuration.
Read the cross-session continuity study
Reuse experience from another task
A task is performed, its result is checked and a lesson is extracted. Memory stores that experience with its sources for retrieval during a different task in a fresh session.
In the synthetic study, Luna succeeds on 22 of 24 tasks with the lesson, compared with 13/24 with the complete trace and feedback, and 7/24 without experience.
Read the learning-between-tasks study
Keep memory consistent after a correction or failure
Trace information to its sources and versions, exclude withdrawn evidence and check an old backup before reusing it.
Across 100 lifecycle scenarios, all 751 valid reads are preserved and all 389 forbidden reads are blocked. The SQLite reference retaining current authority achieves the same result. Detailed measurements include recovery after process termination.
Read the corrections and recovery study

Explore detailed measurements and integration observations

Core 0.3.0a5 ships with installation files, checksums and French and English documentation; the separate policy registry remains at 0.2.0a2. The code, synthetic data, protocols and offline calculations are public.

Across 100 fixed lifecycle scenarios, all 751 valid reads were preserved and all 389 forbidden reads were blocked, matching a SQLite reference with retained current authority. After the core change, four SIGKILL interruption scenarios passed on each Linux host, with observed recovery times of 0.227 to 0.383 seconds.

Across eight synthetic development histories retained between sessions, memory achieves 77 successes out of 96, compared with 29 for a lexical baseline with validity checks. Nine outcomes per configuration remain unknown and stay in the denominator. The campaign used 192 generations without retries; two Codex readers assessed the answers blind to the configuration.

At 1,000 sources and 50 searches, a targeted core optimization reduced instrumented workload time by 28.01% on one host and 27.68% on the other, with the same checked outcomes and stored file sizes. Each figure comes from one before-and-after observation per host.

A later study measures the initial load of 1,000 synthetic sources and the subsequent cycle of additions, searches, reads and withdrawal. Across three paired observations, the cycle took a median 2.35% less time and the initial load a median 29.13% less time, with the same checked outcomes.

At 1,500 sources followed by ten additions and 50 searches, a targeted change to identifier validation reduced instrumented workload time by a median 6.79% and CPU time by 6.77% across three new paired observations. All six runs preserved the expected reads and withdrawal behavior, with identical final storage sizes.

In a separate study, a model completed task A, received feedback on its actual output and extracted a lesson before attempting a different task B in a fresh session.

Across 48 episodes and 288 model calls, Luna succeeded in 22 of 24 B tasks with a lesson, 13 with the complete trace and feedback, and seven without experience. Sol scored 24 of 24 with either a lesson or the complete trace, and 12 without experience. The files produced by all 192 B tasks were independently reopened and checked, including both failed lesson-assisted tasks.

Two sessions of a real agent each passed seven tests on the same thirteen scenarios, with identical quality results. The system message confirmed automatic delivery of stored lessons. A second agent retrieved the experience and produced code that passed the same tests unchanged, in one task. The report records this undeployed proposal and a defect outside those assertions: some metrics and secondary text use False or 0 for missing information.

In 16 tasks where an earlier rule still applied, memory completed 10 tasks, compared with 7 for a local ECC adaptation. In 16 tasks with a new rule, the results were 11 and 14. The study did not establish an advantage under its predefined criteria. The report includes all 128 outcomes across four conditions, correction attempts and resource use.

Role and scope

I design and develop the storage, retrieval and recovery mechanisms, the Python interfaces and the optional HTTP and MCP integrations. I also maintain the public packages, bilingual documentation, standalone examples and tests for failures, concurrent access and evidence withdrawal.

Problem and constraints

A search index or restored backup can still contain evidence that was corrected or withdrawn. A useful memory system must distinguish current evidence, outdated versions and unavailable validation before returning context to an application.

Architecture

SQLite stores immutable versions and links between sources and derived information. A separate authority and freshness witness determine which evidence is still usable. Rebuildable FTS5 indexes find candidates, which are checked again before retrieval.

Typed records distinguish documents, observations, hypotheses, procedures, tasks and feedback. Context can optionally include immutable source references; each complete text-and-reference item and the separators count towards the same budget. Plain text remains the default. The optional HTTP facade also offers a typed-only mode with a fixed workspace and token, configured by the host.

An optional renderer turns supplied, reviewed facts into text using predefined French templates, preserving source versions and passages. The admission module checks the host’s authority and the final output buffer, and reports unknown, conflicting or withdrawn evidence.

Decisions and trade-offs

The authority validates evidence; the index supplies retrieval candidates. Writes use compare-and-swap, and recovery checks old content snapshots against retained current authority, starting in quarantine. The optional registry separates policy proposal, evidence, admission and rollback. The host controls policy activation and permissions.

Testing and verification

Core 0.3.0a5 and registry 0.2.0a2 passed 215 distinct test methods: 166 for the core and 49 for the registry. Testing installed wheels and wheels rebuilt from source archives produced 430 executions per Linux environment, 860 across the two hosts. The public downloads match the tested archives byte for byte. Separate synthetic studies cover corrections, withdrawals, process failures, execution time and learning between tasks.

Resources and links

Usage and integration

The library is released as an alpha. Recovery uses current authority and a freshness witness retained outside the restored content backup. Withdrawal controls subsequent library reads. Exported copies and information already transmitted are handled by the receiving system.

Optional rendering and admission receive supplied, reviewed facts under authenticated host authority. Integration assigns the host responsibility for fact extraction and semantic checks, callback isolation and deadlines, and the durable handoff journal. The host coordinates authorization and publication.

The integration contract distinguishes delivery acknowledgment from tracking how the recipient uses the information. An effect with an uncertain outcome is reported to the host for a decision, without an automatic retry. The documentation provides the recovery and admission contracts.

The learning study covers six task families and twelve synthetic worlds. Recovery measurements cover eight process interruptions. The 1,000-source performance protocol leaves cache state uncontrolled. Each linked report provides its execution conditions, observations and calculations.

The initial integration trial covers eight tasks, with one generation per condition, a preset intent and a restricted catalogue. AI judges assessed the answers. The test harness interrupted one condition during parallel searches; the report retains the available responses and that interruption.

Persistent Memory

Summary

Public results

Keep the thread across sessions

Reuse experience from another task

Keep memory consistent after a correction or failure