loci — Structured Memory for AI Agents

GitHub: https://github.com/bayhax/loci | ClawHub: clawhub install loci

Quick Start

LOCI="node <skill_dir>/scripts/loci.mjs"

# Initialize palace (first time only)
$LOCI init

# Store a memory
$LOCI store work "Switched to Claude Opus model per user preference" --tag model --tag preference

# Recall memories
$LOCI recall "what model does the user prefer"

# Walk through palace (do this during heartbeats)
$LOCI walk

# See overview
$LOCI status

Core Concepts

Domains — Categories that organize memories (like rooms). Each has a capacity limit. Default domains: work, knowledge, people, tools, preferences, archive.

Memories — Individual pieces of context stored in a domain. Each has: - Unique ID (e.g. e3a7f2c1) - Content text - Tags for categorization - Links to related memories - Weight that decays over time

Decay — Memories lose weight exponentially based on time since last access. Formula: weight = base_weight × e^(-decay_rate × days_since_access) Default decay rate: 0.05 (half-life ≈ 14 days).

Links — Bidirectional connections between related memories across any domain.

Commands

Command	Purpose
`init`	Create new palace (once)
`store <domain> <content>`	Add memory. Options: `--tag`, `--link`
`recall <query>`	Search. Options: `--domain`, `--top N`
`walk`	Traverse all memories, report health
`prune`	Remove decayed memories. Options: `--threshold`, `--dry-run`
`status`	Overview of all domains
`inspect <id>`	View memory details + links
`link <id1> <id2>`	Connect two memories
`domains`	List/add/remove domains
`export`	Export as markdown or JSON. Options: `--format md\|yaml`

Integration with Heartbeats

During heartbeat walks, run:

$LOCI walk --decay 0.05

This reports domain health, identifies fading memories, and updates the walk timestamp. Periodically follow with $LOCI prune --dry-run to review candidates for removal.

When to Store vs. When to Skip

Store: Decisions, user preferences, environment quirks, lessons learned, important people/relationships, recurring patterns.

Skip: Transient task details, one-off commands, things already in daily memory files.

Rule of thumb: If future-you would benefit from knowing this in 2 weeks, store it.

Palace File

Default location: ~/.openclaw/workspace/loci_palace.json Override with --palace PATH on any command. Format: JSON. Zero external dependencies — only requires Node.js (ships with OpenClaw).