PARA Memory Skill

Name: para-memory
Version: 1.0.0
Author: OpenClaw Community
License: MIT

Requirements

Required LLM Models (pick one)

Required QMD Collections

The skill expects these QMD collections to be configured:

# ~/.config/qmd/config.yaml
collections:
  memory:
    paths: ["~/workspace/memory"]
    extensions: [".md"]
  para:
    paths: ["~/workspace/para"]
    extensions: [".md"]
  para-facts:
    paths: ["~/workspace/para"]
    extensions: [".json"]

Description

A structured memory system for AI agents based on Tiago Forte's PARA method (Projects, Areas, Resources, Archives). Provides persistent, decaying memory with atomic facts, entity relationships, and intelligent checkpointing.

Features

• •📁 PARA Structure - Organized entity storage (projects, areas/people, areas/companies, resources)
• •🧠 Atomic Facts - Fine-grained facts with metadata (category, status, timestamps)
• •🔗 Entity Relationships - relatedEntities cross-references build a knowledge graph
• •🔄 Supersession Chains - supersededBy tracks fact history and updates
• •🔥 Memory Decay - Hot/Warm/Cold tiers based on access patterns
• •📈 Frequency Resistance - High-access facts resist decay
• •📊 Access Tracking - accessCount and lastAccessed for each fact
• •🤖 LLM-Powered Checkpointing - Automatic fact extraction from conversations
• •📝 Daily Notes Integration - Timeline entries for transient events
• •🔍 QMD Integration - Optional search indexing

Installation

Quick Install

cd /path/to/your/workspace
git clone <skill-repo> skills/para-memory
./skills/para-memory/scripts/setup.sh

Manual Install

1. •Copy para/ template to your workspace root
2. •Copy scripts to scripts/ (or keep in skill folder)
3. •Set up cron jobs (see Configuration)
4. •Optional: Install qmd for search indexing

Configuration

Environment Variables

Decay Thresholds

Frequency Resistance: Facts with accessCount >= 10 stay Hot regardless of recency.

Cron Jobs

# Checkpoint every 30 minutes
*/30 * * * * cd /path/to/workspace && python3 scripts/memory_checkpoint.py cron

# Weekly decay cycle (Sundays 3am)
0 3 * * 0 cd /path/to/workspace && python3 scripts/memory-decay.py

Usage

Manual Checkpoint

python3 scripts/memory_checkpoint.py manual

Quick Decay (Update Summaries)

python3 scripts/memory-decay.py --quick

Full Decay Cycle

python3 scripts/memory-decay.py

File Structure

workspace/
├── para/
│   ├── README.md
│   ├── projects/           # Active work with goals
│   │   └── my-project/
│   │       ├── summary.md
│   │       └── facts.json
│   ├── areas/
│   │   ├── people/         # People entities
│   │   │   └── alice/
│   │   │       ├── summary.md
│   │   │       └── facts.json
│   │   └── companies/      # Organization entities
│   ├── resources/          # Topics of interest
│   └── archives/           # Inactive items
├── memory/
│   ├── 2026-01-31.md       # Daily notes
│   └── ...
└── scripts/
    ├── memory_checkpoint.py
    └── memory-decay.py

Entity Schema

facts.json

{
  "entity": "alice",
  "entity_type": "people",
  "created": "2026-01-31",
  "lastUpdated": "2026-01-31",
  "createdReason": "Direct relationship with user",
  "facts": [
    {
      "id": "ali-001",
      "fact": "Works at Acme Corp as lead engineer",
      "category": "context",
      "status": "active",
      "created": "2026-01-31",
      "lastAccessed": "2026-01-31",
      "accessCount": 3,
      "supersededBy": null,
      "relatedEntities": ["areas/companies/acme-corp"],
      "source": {
        "type": "conversation",
        "timestamp": "2026-01-31T14:30:00",
        "channel": "discord"
      }
    }
  ]
}

Fact Categories

• •relationship - How entities relate to each other
• •milestone - Significant events or achievements
• •status - Current state or situation
• •preference - Likes, dislikes, work style
• •context - Background information

Fact Status

• •active - Current, valid fact
• •superseded - Replaced by newer fact (has supersededBy pointing to replacement)

Integration

With AGENTS.md

Add to your workspace's AGENTS.md:

## Memory

- **PARA:** `para/**/*.json` — structured entities with atomic facts
- Run checkpoint: `python3 scripts/memory_checkpoint.py manual`
- Run decay: `python3 scripts/memory-decay.py --quick`

With QMD Search

# Index PARA entities
qmd update -c para -c para-facts

# Search
qmd search "alice acme" -c para

With Heartbeats

During heartbeat polls, optionally run:

python3 scripts/memory-decay.py --quick

name: para-memory version: 1.0.0 description: Structured memory system for AI agents based on PARA method (Projects, Areas, Resources, Archives) with atomic facts, memory decay, and LLM-powered checkpointing. metadata: clawdbot: emoji: "🧠" requires: plugins: [] skills: [] external: - qmd # Local search indexing (BM25 + vectors) - ollama # Local LLM for checkpoint extraction install: commands: - "ollama pull qwen2.5:7b" # Or llama3.2 - "clawdhub install qmd"

Requirements (Hard Dependencies)

This skill requires local, offline tools for privacy and cost savings:

Required: Local LLM (Ollama)

The checkpoint system uses an LLM to extract facts from conversations. It must be a local Ollama instance for privacy.

# Install Ollama
brew install ollama

# Start Ollama
ollama serve

# Pull a compatible model
ollama pull qwen2.5:7b
# or
ollama pull llama3.2

Required environment variables:

export PARA_OLLAMA_URL="http://localhost:11434/v1"
export PARA_MODEL="qwen2.5:7b"

Required: QMD (Local Search)

For search indexing across your memory corpus. Install via ClawHub:

clawdhub install qmd

Or from source: https://github.com/openclaw/qmd

Python Requirements

pip install openai  # Compatible with Ollama's API

Troubleshooting

Checkpoint Not Extracting Facts

1. •Check LLM is running: curl http://localhost:11434/v1/models
2. •Verify context exists in memory/YYYY-MM-DD.md
3. •Run with verbose: python3 scripts/memory_checkpoint.py manual 2>&1

Summaries Not Updating

1. •Run decay: python3 scripts/memory-decay.py --quick
2. •Check facts.json has lastAccessed fields

Entity Not Created

Entities are created when:

• •Mentioned 3+ times in conversation
• •Direct relationship with user
• •Significant project or milestone

Changelog

1.0.0

• •Initial release
• •PARA structure with atomic facts
• •Memory decay system
• •LLM-powered checkpointing
• •Entity cross-references
• •Supersession chains