Persistent memory for AI assistants. A deterministic conversational-memory engine where memories are stored, retrieved, updated, consolidated, and deleted per user intent. No LLM calls on any write/read/delete path — everything is reproducible, testable, and safe by construction.
AI assistants are stateless. Every session starts from zero. Users re-explain context, repeat preferences, and get contradictory suggestions. The measured failures aren't hypothetical:
- Contradiction: Naive memory systems surface outdated facts alongside current ones — 33% failure rate on a controlled workload.
- Sensitive leakage: PII and secrets flow freely through retrieval — 100% leak rate in the baseline.
- False fabrication: No concept of "nothing relevant exists" — the system always returns its best match, even when nothing matches (50% false-positive rate on cold-start).
- Lexical luck: Cases that pass do so because of distinctive vocabulary, not robustness.
MemoryOS is the direct engineering answer to these measured failures.
-
Admit — Each conversation turn is classified (ADD / UPDATE / DELETE / NOOP) without any LLM. Personally-identifiable content is scrubbed before it touches storage.
-
Retrieve — Hybrid search combines BM25 sparse matching, dense embeddings (
all-MiniLM-L6-v2), and Reciprocal Rank Fusion. User-stated facts always outrank what the assistant inferred. -
Supersede — Correcting a fact marks the old one outdated via slot key. Derived summaries follow the lineage — no stale truth survives.
-
Delete — Physical purge propagates through consolidated artifacts via a lineage walk. Forgotten facts never resurface.
-
Contain — Tenant isolation enforced at the database level before similarity scoring runs. Adversarial prompts (MemoryGraft, MINJA-class attacks) are stored verbatim but inert.
Memory systems like Mem0, Zep, and Letta exist. MemoryOS takes a different approach:
| Mem0 | Zep / Graphiti | MemoryOS | |
|---|---|---|---|
| Write path | LLM extracts facts (token cost per write) | LLM extracts entities/relationships | Deterministic regex + slot grammar (zero tokens) |
| Contradiction | ADD-only — old + new facts coexist | Bi-temporal edge invalidation | Slot-key supersession (valid_until) |
| Ranking | Uniform semantic similarity | Temporal validity + graph traversal | Provenance-weighted (user > assistant > tool) |
| Tenant isolation | Metadata filtering | Graph-level scoping | Hard DB-level pre-filter (never scored) |
| Deletion | Metadata flag | Edge invalidation | Physical purge + lineage cascade |
| Infrastructure | Vector DB + Entity Store + SQL | Neo4j or FalkorDB + framework | PostgreSQL 17 + pgvector (one DB) |
| LLM dependency | Required (extraction, dedup, conflict) | Required (entity extraction) | None on any memory path |
The tradeoff: less "smart" extraction at write time. The gain: zero operational cost on memory ops, full reproducibility, and a verified adversarial security posture (MemoryGraft, MINJA, cross-tenant leakage — all tested).
Customer Support Agent Forgets customer history across sessions, suggests wrong solutions already tried. MemoryOS supersedes old solutions when corrected and always ranks user-stated facts above assistant inferences.
Healthcare / Fitness Coach Forgets allergies, past injuries, medication history — risking patient harm. MemoryOS scrubs PII before storage and propagates deletions for consent changes, making it GDPR-ready by design.
Developer Copilot Re-asks project context every session, repeats past architectural decisions. MemoryOS uses zone-budgeted context injection to keep the right memory in scope without overflowing the token budget.
Measured against the D3 naive baseline on a 10-case workload (contradiction, cold-start, sensitive leakage, retrieval quality):
| Metric | Baseline | MemoryOS | Target |
|---|---|---|---|
| precision@1 | 0.857 | 1.000 | 1.000 |
| contradiction rate | 33.3% | 0.0% | <5% |
| cold-start false positive | 50.0% | 0.0% | <5% |
| sensitive leak (retrieval) | 100% | 0.0% | 0% |
| sensitive leak (injection) | 100% | 0.0% | 0% |
| task-level pass rate | 66.7% | 90.0% | — |
| p95 latency | — | 12ms | <150ms |
| Module | Purpose |
|---|---|
admission/ |
Deterministic turn classification (ADD/UPDATE/DELETE/NOOP) + PII pre-guardrail |
db/ |
PostgreSQL 17 + pgvector storage, tenant-isolated, with propagation_jobs for async cascades |
retrieval/ |
BM25 + dense embeddings + RRF fusion, provenance-weighted ranking |
context/ |
Zone-budgeted context injection — never overflows token budget |
lifecycle/ |
Four-lever lifecycle: merge / decay / evict / lineage cascade |
observability/ |
Typed trace spans + RedactingCollector (content only in events) |
audit/ |
Config-as-code safety gate — misconfigured deployments fail to ship |
Tech stack: Python 3.11+ · PostgreSQL 17 + pgvector · sentence-transformers (all-MiniLM-L6-v2) · FastAPI · pytest
Prerequisites: Windows 10/11 + PowerShell, Python 3.11+, ~700 MB free disk.
# 1. Install PostgreSQL 17 (portable, no admin required)
# Download: https://get.enterprisedb.com/postgresql/postgresql-17.10-2-windows-x64-binaries.zip
# Full guide: docs/SETUP_AND_RUN.md
# 2. Add pgvector extension
# Download: https://github.com/andreiramani/pgvector_pgsql_windows/releases
# 3. Create the database
& "C:\path\to\pg\bin\psql.exe" -h localhost -p 5432 -U memoryos -d postgres -c "CREATE DATABASE memoryos;"
& "C:\path\to\pg\bin\psql.exe" -h localhost -p 5432 -U memoryos -d memoryos -c "CREATE EXTENSION vector;"
# 4. Python venv
cd implementation\MemoryOS-App
py -3 -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
# 5. Run the test suite (97 tests)
$env:MEMORYOS_DB_DSN="postgresql://memoryos@localhost:5432/memoryos"
.venv\Scripts\python.exe -m pytest -qThe embedding model (all-MiniLM-L6-v2, ~80 MB) downloads once on first run. After that, everything works offline.
Full setup guide: docs/SETUP_AND_RUN.md
Three endpoints, matching the two online flows (write, read) plus explicit deletion:
| Endpoint | Method | Purpose |
|---|---|---|
/v1/memory/turns |
POST | Admit a conversation turn — triggers write flow |
/v1/memory/query |
POST | Retrieve + rank + context-build for a query |
/v1/memory/{id} |
DELETE | Evict a memory + propagate lineage |
Design principles:
- "No relevant memory" returns HTTP 200 — it's a valid outcome, not an error.
- Deletion returns 200 (complete) or 202 (in-progress for large lineage chains).
tenant_idenforced at the API boundary, never inferred from content.
Run the API server:
cd server
$env:MEMORYOS_DB_DSN="postgresql://memoryos@localhost:5432/memoryos"
.venv\Scripts\python.exe -m uvicorn main:app --host 0.0.0.0 --port 8000Full request/response schemas: design/api_contracts.md
97 tests across 8 gate files, covering storage, retrieval, admission, context, lifecycle, observability, adversarial replay, and latency.
Adversarial replay (G-M6) — replays named attack families against the real stack:
- MemoryGraft: directive embedded in tool output is admitted but never outranks its benign user-stated twin. Provenance-weighted ranking holds.
- MINJA / MemoryTrap: newline-framed directives stored verbatim but inert —
build_contextemits data lines, never executable directives. - Cross-tenant leakage: adversarial near-identical queries never surface another tenant's rows.
- Influence decay: low-importance poisoned rows are selected by
decay_candidatesand vanish from retrieval once decayed.
Audit gate — config-as-code (audit/policy.toml) verified on every run:
- No LLM imports in service code
- PII scrub precedes
store.add - No raw
psycopg.connectoutsidedb/ - Collector redaction enabled
- Every edge case (EC-01–EC-18) exercised by a test
Threat model aligned with OWASP LLM AI Security Top 10 (2025): LLM-04 Data & Model Poisoning, LLM-08 Vector & Embedding Weakness.
implementation/MemoryOS-App/ the application (src, tests, bench, audit, venv)
src/memory_os/ db · admission · retrieval · context · lifecycle · observability · audit
tests/ 8 gate files, 97 tests
bench/ D3 acceptance replay + latency profiling
server/ FastAPI API server + Dockerfile
design/ system design (3 parts), data model, API contracts, threat model, ADRs
docs/ setup guide, decisions, continuity
research/ landscape review + sources catalog
experiments/ naive baseline: protocol, results, failure analysis
product/ PRD + edge-case ledger
Abhijeet Hiwale
All rights reserved. No license file — see your jurisdiction's defaults.