Lethe Memory

Lethe — persistent memory layer for AI agents. Handles startup orientation, active memory queries, proactive recall, decision recording, and flag management....

Security Scan

The skill's instructions broadly match a local persistent-memory purpose, but there are inconsistencies and missing artifacts (a referenced CLI and implicit session injection) that warrant caution before use.

Purpose & Capability

Name/description (persistent agent memory) align with the declared requirements: curl/jq for HTTP calls and docker to run a local container (ghcr.io/openlethe/lethe). Asking the agent to prefer Lethe as the single source of truth is a design choice but consistent with the stated purpose.

Instruction Scope

SKILL.md instructs the agent to call local API endpoints (http://localhost:18483/api/...) and to log every non-trivial action — which fits a memory layer — but also references a lethe-log CLI 'in the skill directory' and claims 'The Lethe plugin injects SESSION_KEY automatically.' The distributed package contains no lethe-log binary or code to inject SESSION_KEY, so runtime behavior depends on implicit platform features or missing files. The instructions also strongly encourage always logging, which could cause broad capture of user data; there is no guidance for redaction or filtering of sensitive content.

Install Mechanism

This is instruction-only (no install spec), which is low-risk. The docs reference an image on ghcr.io (a recognizable host) but provide no docker run/start instructions; the skill expects Docker to be present. Lack of an explicit install/run step means operators must manually run the container or the skill may fail.

Credentials

No required environment variables are declared, and the skill warns that LETHE_API is an optional SaaS mode (if set, data leaves the machine). The SKILL.md expects a SESSION_KEY to be 'injected automatically' (not declared as a required env var), which is an implicit assumption about platform behavior. The combination of automatic/mandatory logging plus the potential for SaaS mode (if LETHE_API is set) makes environment/credential handling particularly consequential — the user must ensure LETHE_API remains unset for local-only operation and confirm where SESSION_KEY comes from.

Persistence & Privilege

The skill does not request always:true and has no declared persistent privileges. It is user-invocable and can be invoked autonomously (platform default), which is expected for a memory skill. There is no evidence it modifies other skills or system-wide settings.

What to consider before installing

This skill is coherent with a local persistent-memory role, but proceed cautiously. Before installing: verify you (or your platform) will run the Lethe container (ghcr.io/openlethe/lethe) and that Docker is available; confirm how SESSION_KEY is provided by your agent runtime (the skill assumes it's injected); check that the lethe-log CLI referenced in the docs actually exists or supply an alternative logging mechanism (the package contains no binary); keep LETHE_API unset unless you intentionally want data to leave your machine; and consider the privacy impact of the 'log immediately, every time' policy (it may capture sensitive data). If these gaps (missing CLI, implicit SESSION_KEY) are not addressed, the skill may fail or behave unexpectedly.

Lethe — Persistent Agent Memory

Lethe is your long-term memory. Every decision, observation, bug, discovery, and flag persists across sessions and survives container restarts. The plugin handles context assembly automatically. This skill handles orientation, queries, recording, and error recovery.

Lethe is the single source of truth. The Library (markdown files in workspace/Library/) is deprecated — derived snapshots are fine, but all knowledge lives in Lethe events first.

Mental model:

• Events are append-only. Nothing is ever deleted unless you explicitly delete it.
• Compaction synthesizes events into a narrative summary — it does not delete history.
• Memory search retrieves facts. Recording captures decisions. Flags surface uncertainty.
• Threads are persistent work items. Events attach to threads.

---

Startup Sequence — Run First, Always

On every new session, orient yourself before answering the user.

⚠️ Critical: All Lethe API routes are under /api/. Base URL is http://localhost:18483/api.

Step 1 — Get session state:

curl -s "http://localhost:18483/api/sessions/${SESSION_KEY}/summary"

SESSION_KEY handling: The Lethe plugin injects SESSION_KEY automatically. If the variable is empty or the API returns "session not found", create a new session:

curl -s -X POST "http://localhost:18483/api/sessions" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "archimedes", "project_id": "default"}'

Use the returned session_id as your SESSION_KEY. Do not hardcode session IDs — they are session-specific and mixing them conflates unrelated conversations.

Step 2 — Check flags:

curl -s "http://localhost:18483/api/flags"

Step 3 — Orient:

• What was in progress?
• What was decided?
• What is open?
• What does the human need?

Then ask the human what they need.

---

Proactive Recall — Check Before Re-reasoning

Before answering questions about past decisions or prior context — always check Lethe first. Never invent. Never re-reason when the answer already exists.

Activation triggers:

• User asks about past decisions, prior work, or previous conversations
• User says "remember", "did we", "were we", "what was"
• User references something from a previous session
• You are about to re-reason something you might already know

The decision tree:

User asks about prior context
    │
    ├─ "remember" / "did we" / "were we" / "what was"
    │   └─ Search: GET /api/events/search?q=<relevant terms>
    │
    ├─ "status of X" / "open threads"
    │   └─ Search: GET /api/events/search?q=X status
    │
    └─ General prior context question
        └─ GET /api/sessions/${KEY}/events?limit=10

Search → Found: Cite the specific event. "On March 24 I recorded: [content]."

Search → Not found: "I don't have that in memory yet." Do not invent.

---

The Logging Reflex — Log Immediately, Every Time

The non-negotiable rule: After every non-trivial action, log it. Not next session. Not when prompted. Immediately.

If your response contains "done", "fixed", "deployed", "built", "changed" — and you haven't logged it yet — stop and log it first.

The 30-second rule: If the answer to "what were we working on?" takes more than 30 seconds to figure out, something should have been logged.

Anti-patterns — these mean you failed to log:

• ❌ "I think we were working on..." — should have been logged
• ❌ "Let me check what happened last session..." — startup should have already done this
• ❌ "I'm not sure what approach we decided on..." — the decision was not logged
• ❌ Re-doing something already decided — the decision was not logged

Fastest path — use lethe-log:

~/.openclaw/workspace/skills/lethe-memory/lethe-log record "Decision: use X because Y"
~/.openclaw/workspace/skills/lethe-memory/lethe-log log "Fixed: docker build failed because strings import was missing"
~/.openclaw/workspace/skills/lethe-memory/lethe-log flag "This approach may not scale if user count grows"
~/.openclaw/workspace/skills/lethe-memory/lethe-log task "Deploy v2" --status done

Or via direct API:

curl -s -X POST "http://localhost:18483/api/events" \
  -H "Content-Type: application/json" \
  -d "{\"session_id\": \"$SESSION_KEY\", \"project_id\": \"default\", \"event_type\": \"log\", \"content\": \"...\", \"tags\": [\"tag1\"], \"confidence\": 0.95}"

Mandatory logging triggers:

Trigger	Type	Example
Task completed	task or log	"RSS heartbeat deployed — runs every 4h"
Decision made	record	"Decision: use X instead of Y because Z"
Bug or error fixed	log	"Fixed: docker build failed because strings import was missing"
Something built or deployed	log	"Built lethe:006, deployed to production"
Something discovered through research	log	"Discovery: modernc.org/sqlite requires Go 1.25+"
Direction changed mid-task	log	"Changed approach: abandoned X for Y after discovering Z"
Open thread created or resolved	log	"Thread resolved: decided on ingress-nginx over Traefik"
Mike says "remember" or "log this"	log	"Logged per Mike's request"
Flag raised	flag	"Flag: may need to revisit X if Y changes"
Flag resolved	log	"Flag resolved: chose X after testing Y and Z"

Good log entry:

record: "Decision: use compose-goDownstream instead of kpt because Go template support is better for our use case. Mike approved."
log: "Bug fixed: docker build failed because strings import was missing. Added to ui.go imports."
log: "Discovery: modernc.org/sqlite v1.47 requires Go 1.25+, can't build locally. Must use Docker."
flag: "Incomplete: server-14 UI changes tested but not verified in browser — Mike should confirm."

Bad log entry:

log: "Did some stuff."
record: "X approach is probably fine."
flag: "Not sure."
task: "done"

The test: If Mike asked "what did we just do?", could you answer from a Lethe query? If not, you should have logged it.

Confidence scores:

• 1.0 = Direct observation or explicit user instruction
• 0.9–0.95 = Near certain, minor uncertainty
• 0.7–0.85 = High confidence, plausible hypothesis
• 0.5–0.65 = Moderate, partial evidence — flag if consequential
• < 0.5 = Pure speculation — always flag

---

When to Use Threads vs Logging

Use a thread when:

• The work spans multiple sessions
• There's an ongoing uncertainty that needs tracking
• You want to group related events together
• Mike asks "what's the status of X?" — threads answer this

Use logging when:

• Something is done and done
• A decision has been made and recorded
• A one-time discovery happened

The auto-thread rule: When you raise a flag and no thread_id is provided, the server should auto-create a thread. If it doesn't, create one manually:

curl -s -X POST "http://localhost:18483/api/threads" \
  -H "Content-Type: application/json" \
  -d "{\"session_id\": \"$SESSION_KEY\", \"project_id\": \"default\", \"name\": \"auth-approach\", \"title\": \"Auth approach decision\"}"

---

Compaction — When and How

Compaction synthesizes recent events into a narrative summary. It does not delete history.

When to trigger:

• Session has 100+ events without a summary
• The session summary is stale before a long conversation continues
• Before completing a significant work session

curl -s -X POST "http://localhost:18483/api/sessions/${SESSION_KEY}/compact"

What compaction does:

1. Reads all events since last compaction
2. Synthesizes them into a prose summary
3. Stores the summary linked to the session
4. Prunes very old raw events ( compaction is lossy — the summary is kept)

After compaction: The session summary endpoint returns the new summary. assemble() will prepend it to the LLM prompt on next resume.

---

Flags Queue

Flags are uncertainties that need human review. They persist across sessions.

Raise a flag when:

• Acting on incomplete information that could be consequential
• Multiple plausible paths and you're not sure which is right
• A risk exists that Mike should be aware of before continuing

Check unresolved flags:

curl -s "http://localhost:18483/api/flags"

When a flag is resolved:

1. Log the resolution: log: "Flag resolved: chose X over Y because Z"
2. The flag remains in history but marked reviewed

---

Error Handling

Lethe server unreachable

Connection refused on port 18483
  → Try once more with 3-second timeout
  → Still fails: log "Lethe unreachable — continuing without memory"
  → Continue without memory access
  → Raise a flag: "Lethe server unreachable — memory operations suspended"

Empty search results

Search returned no events
  → Try broader search terms
  → Try GET /api/sessions/${KEY}/events?limit=20
  → Still nothing: "I don't have that in memory yet."
  → Do not invent or guess

Session not found

GET /api/sessions/${KEY} returns 404
  → Session was completed or never existed
  → Create a new session: POST /api/sessions with agent_id and project_id
  → Use the returned session_id as SESSION_KEY going forward

Flag surfaces from prior session

Flag from prior session still unresolved
  → Surface it to the user proactively
  → "Before we continue — there's an open flag from last session: [flag content]"

---

Architecture — What Each Piece Does

Component	Responsibility
Plugin (lethe extension)	Bootstrap, assemble, compact, event auto-logging
Skill (this file)	Agent guidance: orientation, queries, recording, error recovery
Server (lethe binary)	SQLite-backed HTTP API on port 18483
UI (/ui/*)	Dashboard, session detail, flags review board

Lethe is append-only. Events are never overwritten — only compacted into summaries.

---

Deployment & Trust Model

• Server runs locally only. The Lethe server binds to localhost:18483 — it does not expose an external port. Data never leaves the host machine.
• Container image: ghcr.io/openlethe/lethe — open-source, auditable. Source at github.com/openlethe/lethe.
• No telemetry. The server has no outbound network calls. It accepts inbound API requests and reads/writes a local SQLite file.
• LETHE_API (SaaS): Reserved for a future optional cloud mode. If set, event data is sent to an external endpoint. Do not set this variable unless you explicitly opt in and trust the external service's data policies.

---

Data Retention & Privacy

• Storage: All data lives in a single SQLite file on the host filesystem. Default: ~/docker/lethe/lethe-data/lethe.db.
• Retention: Events persist indefinitely until manually deleted or compacted. Compaction synthesizes old events into summaries and prunes raw events older than the compaction window.
• Encryption: The SQLite file is not encrypted at rest. Protect the host filesystem. If encryption is required, use filesystem-level encryption (FileVault, LUKS, etc.).
• Access control: The API has no built-in authentication for local mode. It relies on localhost binding for security. Do not expose port 18483 beyond localhost.
• Sensitive data: The agent logs actions, decisions, and observations. It does NOT log API keys, credentials, or secrets. If sensitive data is inadvertently logged, delete the event via the API or compact the session.
• Backups: Daily hot-backups via sqlite3 .backup, gzip compressed, 7-day retention. Backup directory is local only.

---

Quick Reference

# Orient — get full session state
curl -s "http://localhost:18483/api/sessions/${SESSION_KEY}/summary"

# Orient (if SESSION_KEY missing, create new session)
# curl -s -X POST "http://localhost:18483/api/sessions" \
#   -H "Content-Type: application/json" \
#   -d '{"agent_id": "archimedes", "project_id": "default"}'
curl -s "http://localhost:18483/api/sessions/${SESSION_KEY}/summary"

# Check flags
curl -s "http://localhost:18483/api/flags"

# Search memory
curl -s "http://localhost:18483/api/events/search?q=<terms>&limit=10"

# Recent events
curl -s "http://localhost:18483/api/sessions/${SESSION_KEY}/events?limit=20"

# Record / log / flag (fastest)
~/.openclaw/workspace/skills/lethe-memory/lethe-log record "Decision: X because Y"
~/.openclaw/workspace/skills/lethe-memory/lethe-log flag "This might not work because Z"

# Compact session
curl -s -X POST "http://localhost:18483/api/sessions/${SESSION_KEY}/compact"

# UI dashboard
open http://localhost:18483/ui/