Persistent Memory Across Restarts for a Personal Agent

Make personal-agent memory survive systemctl restart, laptop reboots, and container recreates by writing the right state to durable storage - not by stuffing infinite chat into RAM.

Summary

Split memory into preferences, task state, and optional retrieval notes; flush on every meaningful change; keep secrets out of memory stores; restore on host boot before the first chat wake.

Recipe

1. Inventory what must survive. Prefs (timezone, tone, quiet hours), open tasks, approval payloads, processed message ids. Explicitly exclude raw API keys and full mail bodies by default.
2. Pick storage. Start with JSON files + SQLite on a mounted data volume. Add vector retrieval only when keyword/task notes fail.
3. Define schemas with version fields so you can migrate after upgrades.
4. Write-through on change. Do not rely on process shutdown hooks alone; crashes skip them.
5. Load on startup before accepting chat events.
6. Bound what enters the model. Inject a short prefs block + top-k relevant notes, not the entire database.
7. Back up the data directory on a schedule; test restore once.
8. Document wipe: delete data dir, rotate keys if compromise suspected, re-seed prefs from a clean template.

Working Example

File prefs + SQLite notes (illustrative):

import json
import sqlite3
from pathlib import Path
from datetime import datetime, timezone
 
DATA = Path.home() / ".personal-agent"
PREFS_PATH = DATA / "prefs.json"
DB_PATH = DATA / "memory.db"
 
DEFAULT_PREFS = {
    "version": 1,
    "timezone": "America/Los_Angeles",
    "tone": "concise, no emojis",
    "quiet_hours": ["22:00", "07:00"],
    "vip_senders": [],
}
 
def ensure_store() -> None:
    DATA.mkdir(parents=True, exist_ok=True)
    if not PREFS_PATH.exists():
        PREFS_PATH.write_text(json.dumps(DEFAULT_PREFS, indent=2))
    con = sqlite3.connect(DB_PATH)
    con.execute(
        """CREATE TABLE IF NOT EXISTS notes (
            id INTEGER PRIMARY KEY,
            kind TEXT NOT NULL,
            content TEXT NOT NULL,
            created_at TEXT NOT NULL
        )"""
    )
    con.execute(
        """CREATE TABLE IF NOT EXISTS tasks (
            id TEXT PRIMARY KEY,
            status TEXT NOT NULL,
            payload TEXT NOT NULL,
            updated_at TEXT NOT NULL
        )"""
    )
    con.commit()
    con.close()
 
def load_prefs() -> dict:
    ensure_store()
    return json.loads(PREFS_PATH.read_text())
 
def save_prefs(prefs: dict) -> None:
    ensure_store()
    tmp = PREFS_PATH.with_suffix(".tmp")
    tmp.write_text(json.dumps(prefs, indent=2))
    tmp.replace(PREFS_PATH)  # atomic on same filesystem
 
def add_note(kind: str, content: str) -> None:
    ensure_store()
    con = sqlite3.connect(DB_PATH)
    con.execute(
        "INSERT INTO notes (kind, content, created_at) VALUES (?, ?, ?)",
        (kind, content[:2000], datetime.now(timezone.utc).isoformat()),
    )
    con.commit()
    con.close()
 
def recent_notes(limit: int = 5) -> list[str]:
    ensure_store()
    con = sqlite3.connect(DB_PATH)
    rows = con.execute(
        "SELECT content FROM notes ORDER BY id DESC LIMIT ?", (limit,)
    ).fetchall()
    con.close()
    return [r[0] for r in rows]
 
def build_system_context() -> str:
    prefs = load_prefs()
    notes = recent_notes(5)
    return (
        "User preferences (durable):\n"
        f"{json.dumps(prefs, indent=2)}\n\n"
        "Recent notes:\n- " + "\n- ".join(notes or ["(none)"])
    )

On host boot:

def startup() -> None:
    ensure_store()
    prefs = load_prefs()
    # optional: rehydrate in-flight tasks with status != done
    assert prefs.get("version") == 1

Docker/systemd: mount DATA outside the image so redeploys keep prefs.json and memory.db.

Deep Dive

Three memory layers

Clawdbot/OpenClaw-style always-on hosts feel "personal" when durable layers actually reload after process death.

What not to persist by default

• Full email bodies and attachments
• Raw OAuth refresh tokens (use the OS secret store or encrypted secret files separate from "memory")
• Complete chat transcripts forever
• Shell command output that may contain secrets

If you need audit logs, store them as ops logs with retention and redaction - not as model memory.

Write-through and atomicity

Crash mid-write can corrupt JSON.

Write to a temp file, then replace().

For SQLite, use transactions around multi-row task updates.

Flush after approvals, pref edits, and task status changes - the moments you cannot afford to lose.

Injection into the prompt

Every wake should rebuild a small context block:

1. System policy (code)
2. Prefs snapshot (durable)
3. Active task (if any)
4. Retrieved notes (optional, top-k)
5. Current chat message

Do not replay the entire SQLite history into the model. That burns money and confuses priorities.

Migrations

Include "version": 1 in prefs and a schema_migrations table for SQL.

On startup, run additive migrations before serving traffic.

Keep a backup before migrating on a VPS.

Backup and restore

Test restore on a spare directory before you need it.

Multi-device caution

Two hosts writing one networked volume without coordination will corrupt task state.

Prefer a single active writer (one VPS) or an explicit primary.

Gotchas

1. Memory only in the model provider's "memory product". You still need local task/approval state the host controls.
2. Container without a volume. Beautiful amnesia on every deploy.
3. Embedding every email. Cost, privacy, and retrieval noise; start structured.
4. Model-writable prefs without review. The agent can "remember" insecure defaults; log diffs and gate security keys.
5. Huge notes. Cap length; summarize offline if needed.
6. Clock and timezone bugs. Store UTC timestamps; render in prefs timezone.
7. Forgetting processed message ids. Restarts re-handle the same chat update and double-act.
8. Backing up unencrypted memory to random cloud folders. Encrypt or use a trust-appropriate target.

Alternatives

FAQs

Related

• Self-Hosted Personal Agents Basics - prefs file sketch
• The Self-Hosted Personal Agent Mental Model - where memory sits in the host
• Setting Up Clawdbot/OpenClaw on a VPS or Local Machine - data directory layout
• Self-Hosted Personal Agents Best Practices - retention and wipe habits
• What a Personal AI Agent Actually Does Day to Day - what is worth remembering
• Long-Term Memory - deeper memory patterns (section)

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.