loci — Structured Memory for AI Agents

GitHub: https://github.com/bayhax/loci | ClawHub: INLINECODE0

Quick Start

CODEBLOCK0

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
INLINECODE3	Create new palace (once)
INLINECODE4

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:

CODEBLOCK1

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).