Total Recall — SKILL.md

Overview

Total Recall is a git-based memory backend that stores memories as structured markdown files on a dedicated orphan branch (

openclaw-memory

_memory/

git log --grep

git grep

Prerequisites

• Git (version >= 2.20) — pre-installed on macOS and most Linux distributions.
• A POSIX shell (bash or zsh).
• No external services, databases, or runtimes required.

Verify with:

git --version

Configuration

Configuration is stored in

config.json

backend

"totalrecall"

branch

"openclaw-memory"

memory_dir

"_memory"

file_format

"markdown"

relevance.method

"time_decay"

relevance.formula

"max(0.2, 1.0 - (days_ago * 0.043))"

relevance.today

1.0

relevance.this_week

0.7

relevance.this_month

0.4

relevance.older

0.2

search.max_results

20

store.commit_prefix

"memory:"

Usage

All operations target the

openclaw-memory

git show

git checkout

git worktree

Store

To store a memory with key

auth-decision

# Save current branch
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)

# Switch to memory branch
git checkout openclaw-memory

# Create memory file with structured content
TIMESTAMP=$(date -u +"%Y-%m-%dT%H-%M-%S")
FILENAME="_memory/${TIMESTAMP}_auth-decision.md"

cat > "$FILENAME" << 'MEMORY_EOF'
---
key: auth-decision
timestamp: 2026-03-17T14:30:00Z
tags: [auth, architecture, decision]
---

# Auth Decision

We chose JWT with RS256 signing for the auth middleware.
Refresh tokens use httpOnly cookies for storage.
MEMORY_EOF

# Commit the memory
git add "$FILENAME"
git commit -m "memory: auth-decision — JWT auth middleware decision"

# Return to working branch
git checkout "$CURRENT_BRANCH"

File naming convention:

{ISO-timestamp}_{slugified-key}.md

• Timestamp format:

  YYYY-MM-DDTHH-MM-SS

  (colons replaced with hyphens for filesystem safety)
• Key slug: lowercase, hyphens for spaces, alphanumeric and hyphens only

Commit message convention:

memory: {key} — {brief description}

git log --grep

Retrieve

To retrieve a memory by key:

# Search for the key in commit messages on the memory branch
git log openclaw-memory --grep="memory: auth-decision" --format="%H %ai %s" --max-count=5

# Get the file path from the most recent matching commit
COMMIT_HASH=$(git log openclaw-memory --grep="memory: auth-decision" --format="%H" --max-count=1)
FILEPATH=$(git diff-tree --no-commit-id --name-only -r "$COMMIT_HASH" | grep "_memory/")

# Read the file content without switching branches
git show "openclaw-memory:$FILEPATH"

Output construction — build the contract JSON from the results:

{
  "query_echo": "auth-decision",
  "results": [
    {
      "content": "We chose JWT with RS256 signing for the auth middleware...",
      "relevance": 1.0,
      "source": "totalrecall",
      "timestamp": "2026-03-17T14:30:00Z"
    }
  ],
  "result_count": 1,
  "status": "success",
  "error_message": null,
  "error_code": null,
  "backend_duration_ms": 45,
  "normalized_relevance": 1.0,
  "backend": "totalrecall"
}

Search

To search memories by pattern across all memory files:

# Search commit messages for pattern
git log openclaw-memory --grep="auth" --format="%H %ai %s"

# Search file contents on the memory branch for a pattern
git grep -l "JWT" openclaw-memory -- "_memory/"

# Read matching files
for FILE in $(git grep -l "JWT" openclaw-memory -- "_memory/"); do
  echo "--- $FILE ---"
  git show "$FILE"
done

For broader search with context:

# Full-text search with surrounding lines
git grep -n -C 2 "pattern" openclaw-memory -- "_memory/"

# Case-insensitive search
git grep -il "jwt" openclaw-memory -- "_memory/"

Interface Contract

Input

• store(key, content, metadata?)

  — Create a markdown file on the memory branch and commit it.

• retrieve(query, options?)

  — Search commit messages with

  git log --grep

  , read matching files via

  git show

  .

• search(pattern, scope?)

  — Search file contents with

  git grep

  on the memory branch.

Output Format

All backends return the same JSON structure:

{
  "query_echo": "original query string",
  "results": [
    {
      "content": "...",
      "relevance": 0.0,
      "source": "totalrecall",
      "timestamp": "ISO8601"
    }
  ],
  "result_count": 0,
  "status": "success | partial | empty | error",
  "error_message": null,
  "error_code": null,
  "backend_duration_ms": 0,
  "normalized_relevance": 0.0,
  "backend": "totalrecall"
}

Failure Codes

BACKEND_UNAVAILABLE

QUERY_TIMEOUT

EMPTY_RESULT

PARTIAL_RESULT

BACKEND_ERROR

Relevance Normalization

Total Recall uses time-decay relevance scoring. There is no semantic similarity — relevance is purely a function of how recently the memory was stored.

Formula:

relevance = max(0.2, 1.0 - (days_ago * 0.043))

This produces a continuous decay curve that roughly aligns with these buckets:

The

normalized_relevance

Router Integration

• Normalized relevance >= 0.4 -> "good enough", no fallback needed.
• Normalized relevance < 0.4 or status = empty -> trigger fallback to another backend.
• status = error -> immediate fallback, log error.

Limitations

• No semantic search. Total Recall uses literal text matching (

  git grep

  ). It cannot understand that "authentication" and "login" are related concepts. If the query uses different words than the stored memory, it will not match.
• No relationship or graph queries. Cannot answer "what decisions led to X" unless those links are explicitly stored in the memory content.
• Time-based relevance only. A highly relevant old memory scores lower than a trivial recent one. The scoring model has no understanding of content importance.
• Branch switching overhead. Store operations require switching to the memory branch and back, which can be disruptive during active development. Use

  git worktree

  to mitigate this.
• Linear scaling. Search performance degrades linearly with the number of stored memories. Git grep is fast, but thousands of memory files will eventually slow down.
• No concurrent writes. Git does not support concurrent commits safely. Simultaneous store operations from multiple agents may conflict.
• Keyword matching is case-sensitive by default. Use

  -i

  flag with

  git grep

  and

  git log --regexp-ignore-case

  for case-insensitive matching.

Tier

Starter — Included in the $49 package. Zero additional cost, zero additional dependencies.