PAI Memory System [v0.2]

[dxcore35]

Claude Memory System

A production-ready memory architecture for AI agents that never forgets.
Built on the principle that memory is infrastructure, not a feature.

---

📖 For Humans: How This Actually Works

Imagine if you had a super-efficient secretary who followed you around 24/7.

1. Short-term memory: When you say something, they write it on a sticky note.
2. Long-term memory: At the end of the day, they file these notes.
   • If it's "I like coffee", they put it in the "Preferences" folder.
   • If it's "My sister's name is Sarah", they put it in a fireproof safe (because it's important and rarely changes).
   • If it's "I'm hungry right now", they throw it away after lunch (because it stops being true).

Why is this better than normal AI memory?

Normal AI tries to re-read the entire transcript of your life every time you say "Hello". This is slow, expensive, and confusing.

This system works like your own brain:

• It forgets trivial details (fast decay).
• It reinforces important facts.
• It connects the dots (associating "Sarah" with "Sister").
• It allows Human Review (you can read and edit your own memory).

---

🔄 The Full Memory Lifecycle

This isn't just a database; it's a living ecosystem with daily maintenance cycles.

                                  DAILY MAINT. SCRIPT (3:00 AM)
                                  ┌───────────────────────────┐
                                  │ 1. CHECK DECAY SCORES     │
      USER INPUT                  │    (Is memory old/unused?)│
          │                       │                           │
          ▼                       │ 2. RE-CLASSIFY            │
   ┌─────────────┐                │    (Is it still true?)    │
   │  INGESTION  │                │                           │
   │ (Extractor) │                │ 3. PRUNE GRAPH            │
   └──────┬──────┘                │    (Remove dead links)    │
          │                       └─────────────┬─────────────┘
          ▼                                     │
   ┌─────────────┐                        ┌─────▼─────┐
   │ NEW MEMORY  │                        │           │
   │    ITEM     │───────────────────────►│  ARCHIVE  │
   └──────┬──────┘    (If Decayed)        │ (Deleted) │
          │                               │           │
          ▼                               └───────────┘
   ┌─────────────┐
   │ CLASSIFIER  │◄───── Is it Important? (1-5)
   └──────┬──────┘◄───── Is it Stable? (1-5)
          │
          ├─────────────────────────────────┐
          ▼                                 ▼
   ┌─────────────┐                   ┌─────────────┐
   │  LONG-TERM  │                   │ REVIEW QUEUE│
   │   STORAGE   │                   │ (Uncertain) │
   └──────┬──────┘                   └──────┬──────┘
          │                                 │
          │         WEEKLY REVIEW           │
          └───────────────► ┌─────────────┐ ◄───┘
                            │    HUMAN    │
                            │ (You Mode)  │
                            └─────────────┘

There are two loops keeping the system healthy:

1. The Automatic Loop (Daily): Scripts run every night to decay trivial memories ("I'm hungry") and reinforce repeated ones.
2. The Human Loop (Weekly): You review the "Inbox" of uncertain memories to verify or delete them.

---

🧠 Core Philosophy

"Memory isn't a hard drive. It's a process. You can't just store data; you have to give it a lifespan and let it evolve."

This system solves the three fundamental problems with standard AI memory:

1. Context window overflow → Tiered hierarchical storage
2. Conflicting information → Conflict resolution with supersession
3. Irrelevant retrieval → Smart category selection + decay scores

---

📐 Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    SHORT-TERM MEMORY                        │
│              (Checkpoints - Session State)                  │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                    LONG-TERM MEMORY                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  Resources  │  │   Items     │  │   Categories        │  │
│  │  (Layer 1)  │→ │  (Layer 2)  │→ │   (Layer 3)         │  │
│  │  Raw Data   │  │Atomic Facts │  │ Evolving Summaries  │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
│                           │                                  │
│                    ┌──────▼──────┐                          │
│                    │   Graph     │                          │
│                    │  Memory     │                          │
│                    │ (Triplets)  │                          │
│                    └─────────────┘                          │
└─────────────────────────────────────────────────────────────┘

The Three-Layer Hierarchy

Layer 1: Resources (Raw Data)

Immutable source of truth.

~/.claude-memory/resources/2026-01-18/
├── abc123.json    # Original conversation transcript
└── def456.json    # Uploaded document

Layer 2: Items (Atomic Facts)

Individual units of knowledge extracted from resources.

// items/preferences/dark_mode.json
{
    "content": "Prefers dark mode for everything",
    "category": "preferences",
    "importance": 3,    // 1-5 Scale
    "stability": 4,     // 1-5 Scale
    "confidence": 0.9,
    "provenance": { ... }
}

Layer 3: Categories (Evolving Summaries)

Human-readable summaries for fast retrieval.

# Preferences

- #20260119-01 ✓ [2026-01-19]: Prefers TypeScript over JavaScript        | fixed
- #20260119-02 x [2026-01-19]: I dropped my phone on Friday                 | temporary

---

⚖️ Memory Classification Framework

This is the "engine" of forgetting. Every memory is classified on two dimensions:

                    IMPORTANCE (1-5)
                    Low → High
                    
    ┌─────────────┬─────────────┐
    │   FORGET    │   ARCHIVE   │
    │  (decay)    │  (on change)│  ← Can Change
C   ├─────────────┼─────────────┤
H   │   STALE     │  PERMANENT  │
A   │  (slow decay)│ (no decay) │  ← Stable
N   └─────────────┴─────────────┘
G
E

Classification Scale (1-5)

IMPORTANCE - How important to user's identity/life:

Score	Meaning	Examples
1	Trivial	Weather today, random comment
2	Minor	Temporary preference, casual mention
3	Moderate	Work project, tool preference
4	High	Job, relationships, significant habits
5	Core	Identity, family, health conditions, allergies

STABILITY - How likely to change:

Score	Meaning	Examples
1	Changes often	Current task, mood, temporary state
2	Changes sometimes	Current project, learning something
3	Moderately stable	Job, preferences, regular habits
4	Stable	Relationships, established skills, location
5	Permanent	Name, allergies, family relations, physical traits

Decay Behavior

Quadrant	Condition	Behavior	Half-life
PERMANENT	importance≥4 AND stability≥4	Never decay	∞
ARCHIVE	importance≥4	No decay, superseded on contradiction	∞
STALE	stability≥4, low importance	Slow decay	60-125 days
FORGET	Both low	Fast decay	5-30 days

Examples:

Memory	Importance	Stability	Behavior
"Allergic to shellfish"	5	5	PERMANENT
"Partner: Maya"	5	4	ARCHIVE (supersede on new partner)
"Working on payment PR"	2	1	FORGET (5-day half-life)
"Prefers TypeScript"	3	3	DECAY (45-day half-life)
"Lives in SF"	4	4	PERMANENT

---

🔍 Smart Retrieval & Token Budget

We don't load everything. We use a tiered retrieval strategy to save context window.

Query: "What programming languages does the user know?"

Step 1: List category names → ["preferences", "technical", "work", ...]
Step 2: LLM selects relevant → ["technical"]
Step 3: Load only "technical.md" (300 tokens vs 1500 total)
Step 4: Check sufficiency → "Can this answer the query?"
Step 5: If no → drill down to Items → then raw Resources

Token Savings:

• Load Everything: ~1,500+ tokens
• Smart Retrieval: ~300 tokens (5x Efficiency)

---

📊 Performance & Benchmarks

Metric	Baseline	After Optimization
Accuracy Score	82/100	98/100
Items Extracted	39	77
Unique Entries	~60%	~95%
Duplicates	Many	Minimal
LLM Calls per Text	~25	~6

---

📁 File Structure

~/.claude-memory/
├── resources/           # Layer 1: Raw data
│   └── 2026-01-18/
│       └── *.json
├── items/              # Layer 2: Atomic facts
│   ├── preferences/
│   ├── technical/
│   ├── work/
│   └── relationships/
├── categories/         # Layer 3: Summaries
│   ├── preferences.md
│   ├── technical.md
│   ├── relationships.md
│   └── ...
├── graph/              # Knowledge graph
│   ├── nodes.json
│   └── edges.json
├── checkpoints/        # Session state
└── sequence.json       # Global counter

---

Usage

# Memorize
claude-memory memorize "I prefer TypeScript and use VS Code"

# Retrieve
claude-memory retrieve "What IDE does the user prefer?"

# Create a checkpoint
claude-memory checkpoint save my-session

# View memory stats
claude-memory stats

Python API

from claude_memory import memorize, retrieve

# Store memories
memorize("My partner Maya is helping with the UI design")

# Query with context
context = retrieve("Who is helping with design?")
# Returns: "Maya → partner (designer, helping with UI)"

---

Storage Locations

Component	Location	Purpose
Prompt Registry	brain/system/prompt_registry.jsonl	All prompt templates used
Anti-patterns	brain/memory_guidelines.md	Negative constraints for extraction
Trash	trash/	Deleted memories (recoverable)
Archive	archive/	Decayed memories

---

⚡ Performance Optimization

The system is optimized for minimal LLM round-trips while maintaining quality.

Bottleneck Analysis

Problem: Original architecture made ~25 LLM calls per text ingestion:

• 1 extraction call
• 10 re-classification calls (one per item)
• 10 importance rating calls
• 4 summary evolution calls

Solution: Consolidate into single-pass extraction.

Optimizations Applied

Optimization	Impact	Calls Saved
Single-pass extraction	Extract content, category, importance, stability in one call	~20 calls
Trust valid categories	Skip re-classification when LLM provides valid category	~10 calls
Batch summary evolution	One write per category, not per item	~5 calls

Benchmark Results

Metric	Before	After	Improvement
Total time (6 conversations)	~10-15 min	~5-6 min	50-60% faster
LLM calls per text	~25	~6	76% reduction
Memory quality	Baseline	+4% more items	No degradation

Context Budget

┌─────────────────────────────────────────────────────────────┐
│ 32K Context Budget Breakdown                                │
├─────────────────────────────────────────────────────────────┤
│ Base System Prompt:        ~150 tokens (0.5%)               │
│ Extraction prompt:       ~1000 tokens (3%)                  │
│ Input text:               ~500 tokens (1.5%)                │
├─────────────────────────────────────────────────────────────┤
│ USED:                    ~1750 tokens (5.5%)                │
│ AVAILABLE:              ~30,250 tokens (94.5%)              │
└─────────────────────────────────────────────────────────────┘

Note: Context is not the bottleneck—LLM call count is. Reduce sequential calls for maximum speedup.

---

🛠️ Key Components

File	Purpose
storage.py	Three-layer hierarchy management
llm_utils.py	LLM abstraction + extraction + classification
memorize.py	Write path: conversation → memories
retrieve.py	Read path: query → relevant context
checkpoint.py	Session state management
graph_memory.py	Knowledge graph operations

---

🎯 Design Principles

1. Memory is infrastructure, not a feature
2. Extract facts, not transcripts
3. Newer information supersedes older
4. Important memories never decay
5. Classify at extraction time
6. Retrieve only what's needed

---

📖 Based On

Architecture inspired by @rohit4verse's article on building agents that never forget.

Context-Engineered Human–AI Collaboration for Long-Horizon Tasks:
A Case Study in Governance, Canonical Numerics, and Execution
Control
This version: OSF preprint, DOI https://doi.org/10.17605/OSF.IO/VMK7Y

---

License

MIT License

[DolphusCY]

@dxcore35 I was just asking PAI about this very thing today. I was wondering if it had a graph / RAG system. If I understand this correctly... this would do exactly that and more correct? It would also help with token usage over time, to my understanding right?

[dxcore35]

@DolphusCY

1. It is a Graph / RAG System
   Standard RAG often just retrieves chunks of text based on similarity. This system is much smarter because it combines three layers:

It is RAG (Retrieval): instead of feeding the AI your whole history, it uses Smart Retrieval. When you ask a question, it identifies relevant Categories (Layer 3), picks the specific .md summary files needed, and only loads those into the context.

There is no Vector Database (like Pinecone, Chroma, or Weaviate) just a markdown files and "smart scripts".

It is a Graph: The architecture explicitly lists a graph/ directory containing nodes.json and edges.json (Triplets). It doesn't just store "Sarah" and "Sister" separately; it "connects the dots" to understand the relationship between them. This allows the system to perform Conflict Resolution (superseding old data with new data) rather than just retrieving conflicting facts.

Saved as JSON

2. It radically optimizes Token Usage
   You are exactly right that this helps with tokens over time. It attacks token bloat from two angles:

Input Efficiency (The "Engine of Forgetting"): Most AI memory systems get clogged with useless data (like "I'm hungry"). This system runs a Daily Maintenance Script that checks Decay Scores. If a memory has low "Importance" (1-2) and low "Stability," it is deleted. You never waste tokens processing irrelevant history again.

Context Efficiency (5x Savings): The benchmarks in the text show that instead of loading a full context (~1,500 tokens), the tiered retrieval system loads only the necessary atomic facts (~300 tokens). This keeps your interaction fast and cheap, even as your database grows to millions of facts.

[DolphusCY]

@dxcore35 thanks so much for the detailed explanation... really appreciate it. When can I have it 😂😂😂.

[dxcore35]

@dxcore35 thanks so much for the detailed explanation... really appreciate it. When can I have it 😂😂😂.

Ask your PAI AI :)

[klittle32]

I like that the user data is stored outside of the PAI codebase and outside of one's .claude directory in this model.

[ShaneDugas]

This is very interesting. I need to read it a couple more times to get my head wrapped around it. I'm currently using a Langchain Postgres custom implementation that I built mostly so I could offload the work to a local OLAMA server, but not convinced it's good for the long term.

[madeinoz67]

thanks for sharing, this is a fantastic idea, Ive just added and release this in my Knowledge Pack (with acknowledgement) - https://github.com/madeinoz67/madeinoz-knowledge-system.

[jgmontoya]

Interesting idea! I'd suggest the following adjustment: Instead of fully relying on automated scripts running on cron, imo there should be automated checks running on hooks that allow the daily maintenance script to be called through user interactions. I think it's common to not necessarily have (or want) something running 24/7, but it can be easily "patched" by keeping track of when was the maintenance script ran last, and trigger it if we need to (in a fully async/background manner)

[virtualian]

@jgmontoya, sorry to disagree, but I believe PAIs (will) need to be "always-on" to be truly agentic and self-improving. While incremental steps are useful, the 24/7 end state must be planned.

@danielmiessler's deliberate (or accidental?) decision to integrate PAI into CLI-based agents is brilliant, but this architecture has drawbacks. I have installed PAI on my MacBook; I also use a MacMini. I want to use the same PAI on both, but I haven't (yet) worked out how to sync my PAI between the two, or have one I can use on both.

While mentioning OpenClaw might be contentious here, its access via messaging, web-ui, and TUI, and thus its required always-on architectural model, solves my access/instance pain points.

I'm not ditching PAI because I like Daniel's ethos, vision, philosophy, and engineering discipline. Therefore, my mind is racing with potential solutions, but I haven't reached any conclusions. Sorry!

[danielmiessler]

This is all great discussion here. I am currently working on this. No problem mentioning OpenClaw, it's a great project. I just want our own version that we trust and can control and understand. Working currently on PAIWorker, which is the Chat-enabled PAI Worker that will be able to take work from our work github, start working on it, proactively do tasks, and yes—do all this 24/7. OpenClaw made it obvious that this is a requirement for any platform going forward. PAI thus far has been focused around us, and interactive. But we need the expanded scope too, of PAI Workers, that can work 24/7 and be proactive. This was all anticipated here! https://danielmiessler.com/blog/personal-ai-maturity-model

…

On Tue, Feb 10, 2026 at 11:10 AM, virtualian < ***@***.*** > wrote: @ jgmontoya ( https://github.com/jgmontoya ) , sorry to disagree, but I believe PAIs (will) need to be "always-on" to be truly agentic and self-improving. While incremental steps are useful, the 24/7 end state must be planned. @ danielmiessler ( https://github.com/danielmiessler ) 's deliberate (or accidental?) decision to integrate PAI into CLI-based agents is brilliant, but this architecture has drawbacks. I have installed PAI on my MacBook; I also use a MacMini. I want to use the same PAI on both, but I haven't (yet) worked out how to sync my PAI between the two, or have one I can use on both. While mentioning OpenClaw might be contentious here, its access via messaging, web-ui, and TUI, and thus its required always-on architectural model, solves my access/instance pain points. I'm not ditching PAI because I like Daniel's ethos, vision, philosophy, and engineering discipline. Therefore, my mind is racing with potential solutions, but I haven't reached any conclusions. Sorry! — Reply to this email directly, view it on GitHub ( #527 (reply in thread) ) , or unsubscribe ( https://github.com/notifications/unsubscribe-auth/AAAMLXXS5ULNYSLBTPK7KK34LIUJBAVCNFSM6AAAAACTF6UYNOVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTKNZWGA2TAMA ). You are receiving this because you were mentioned. Message ID: <danielmiessler/Personal_AI_Infrastructure/repo-discussions/527/comments/15760500 @ github. com>

[virtualian]

@dxcore35 This is great.

I see you say "Based on":

Architecture inspired by @rohit4verse's article on building agents that never forget.

Context-Engineered Human–AI Collaboration for Long-Horizon Tasks:
A Case Study in Governance, Canonical Numerics, and Execution
Control (https://doi.org/10.17605/OSF.IO/VMK7Y)

I assume you are refering to Rohit Sharma article Building a Truly adaptive AI Agents with Long-Term Memory, which describes LangMem.

I haven't looked at LangMem, or compared it to your proposal, but did you consider a LangMem-based solution for PAI? It has an MIT License.

[dxcore35]

@danielmiessler Some "nano-versions" of OpenClaw for reverse-inspiration:

https://github.com/gavrielc/nanoclaw
https://github.com/HKUDS/nanobot
https://github.com/rocopolas/FemtoBot

[danielmiessler]

Yes, these were really good. Thank you!