v1.1.0 — Now available on PyPI

Observable Memory Infrastructure
for AI Agents

An operating system for long-lived agent memory — hierarchical, explainable, and self-managing. Replace passive vector dumps with human-like memory layers.

Get Started pip install memctrl uvx memctrl
# Install via pip or uv
$ pip install memctrl
# or: uvx memctrl (no install needed)

$ memctrl init
# Created .memoryrc + .memctrl/memories.db

$ memctrl add "we use FastAPI + PostgreSQL" --layer project
# Added memory to project layer (never expires)

$ memctrl query "what is our stack?"
# Trace: root -> project -> tech_stack -> FastAPI + PostgreSQL

$ memctrl otel-export --output spans.json
# Export memory operations to OpenTelemetry

Why Vector Databases Are Not Enough

Most agent memory today is RAG in a trench coat. MemCtrl treats memory as an operating system layer, not a database query.

Capability Vector RAG MemCtrl
Retrieval logic Cosine similarity (black box) Hierarchical tree traversal with trace
Explainability "Score: 0.87" root -> project -> backend -> fastapi
Lifespan control Manual cleanup Rule-driven expiry + never-forget lists
Knowledge consolidation None Automatic session -> project merging
Memory provenance None Full audit: source, confidence, trace
Observability None OpenTelemetry gen_ai.memory.* exporter
Confidence decay Static forever Inferred facts fade if not reinforced
Audit trail None Complete trigger log
Privacy Cloud embeddings Local SQLite only

Human-Like Memory Architecture

MemCtrl implements a cognitive memory pipeline inspired by how humans actually remember.

1

Input

Chat, code, events, or files enter the system

2

Security Scan

Secrets and PII are redacted before storage

3

Memory Extractor

LLM extracts facts with confidence scoring

4

Memory Layers

Project (forever), Session (7 days), User (90 days)

5

Reflection & Decay

Auto-summarize sessions; inferred facts decay if not reinforced

6

Tree-Based Retrieval

LLM reasons over structure with provenance tracking

7

OpenTelemetry Export

Export memory operations to any OTel-compatible backend

Benchmarks

We measure what actually matters for agent memory systems.

Context Retention (10-turn conversation) Baseline 62% → MemCtrl 91%
Retrieval Explainability Baseline 0% → MemCtrl 100%
Memory Management Overhead Manual → Zero ops
Long-Horizon Task Success Baseline 45% → MemCtrl 78%
Repeat Query Latency Baseline 50-500ms → MemCtrl <1ms

Core Concepts

The building blocks of agent cognition.

M

Memory Layers

Project, session, and user layers with different lifespans. Like human semantic, working, and episodic memory.

R

Reflection Cycle

Automatically refine and summarize memories. Session notes consolidate into permanent project knowledge.

C

Cognitive Compression

Distill verbose conversations into dense, actionable facts without losing meaning.

T

Trace Retrieval

Every answer includes the exact reasoning path taken through the memory tree. Fully explainable.

D

Confidence Decay

Inferred facts gradually lose confidence unless reinforced. Explicit facts persist forever. No stale memory pollution.

P

Retrieval Provenance

Every retrieved memory carries a full audit trail: source, confidence, match reason, and trace path.

O

OpenTelemetry

First reference implementation for gen_ai.memory.* conventions. Export to Datadog, Grafana, Jaeger.

A

Adaptive Recall

Context-aware retrieval that considers recency, relevance, and confidence together.

S

Security First

Secrets and PII are redacted before storage. Never-forget lists protect sensitive memories.

Give your agents a memory

Join developers building the future of AI cognition.

Star on GitHub pip install memctrl