Documentation

Complete reference for the Rememora CLI — persistent, cross-agent memory for AI coding assistants.

Installation

Homebrew (recommended)

$ brew install Rememora/tap/rememora

From Source

$ git clone https://github.com/Rememora/rememora.git
$ cd rememora
$ cargo install --path .

GitHub Releases

Pre-built binaries are available on the Releases page.

Feature Flags

$ cargo install --path . --features embed-candle,metal

Quick Start

# Register a project
$ rememora project add myapp --path /path/to/myapp \
    --description "Mobile app" \
    --stack "react-native,typescript"

# Start a tracked session
$ rememora session start --agent claude-code \
    --project myapp \
    --intent "implementing auth flow"
  Session started: 01JARW...

# Save memories as you work
$ rememora save "Uses expo-secure-store for token storage" \
    --category decision --project myapp --importance 0.8

# Search memories
$ rememora search "authentication" --project myapp

# End session
$ rememora session end 01JARW... \
    --summary "Auth flow complete." \
    --working-state "Need to add biometric auth."

Agent Setup

Claude Code: Install as Plugin (Recommended)

Two commands, fully autonomous from there:

# 1. Add the Rememora marketplace
$ claude plugin marketplace add Rememora/rememora

# 2. Install the plugin
$ claude plugin install rememora@rememora

# For project-wide install (shared via git):
$ claude plugin install rememora@rememora --scope project

After installing, restart Claude Code. The plugin auto-detects your project from the working directory.

What you get

Claude Code: Alternative (CLAUDE.md)

If you prefer manual control instead of the plugin, add to ~/.claude/CLAUDE.md:

## Rememora Memory System
On session start:
1. `rememora context --auto`
2. `rememora session start --agent claude-code
     --project <name> --intent "..."`

During work, save discoveries:
- `rememora save "..." --category decision --project <name>`

Before ending:
- `rememora session end <id> --summary "..." --working-state "..."`

Codex

Add to ~/.codex/config.toml:

system_prompt = """
On session start: run `rememora context --auto` and
  `rememora session start --agent codex ...`
Save important discoveries with `rememora save ...`
Before ending: `rememora session end <id> --summary "..." ...`
"""

Gemini CLI

Add to ~/.gemini/GEMINI.md or your system instructions file using the same pattern as the Claude Code CLAUDE.md approach.

Auto-Setup (All Agents)

Rememora can also auto-detect and configure all installed agents at once:

# Preview what would be configured
$ rememora setup

# Apply the configuration
$ rememora setup --apply

Memories

Memories are the fundamental unit of knowledge in Rememora. Each memory has:

• URI — hierarchical identifier (e.g., rememora://projects/myapp/memories/decision/zustand-over-redux)
• Category — one of 6 types (preference, entity, decision, event, case, pattern)
• Content — the actual knowledge, with optional 3-tier structure (abstract/overview/content)
• Importance — 0.0 to 1.0, blended with hotness for ranking
• Tags — comma-separated for additional filtering
• Provenance — source agent, session, and timestamps

Memories are never hard-deleted. Instead, they are superseded by newer memories, preserving a full audit trail.

Sessions

Sessions track agent work periods and enable cross-agent handoffs.

• start — begins tracking with agent name, project, and intent
• end — closes with summary and working state
• transfer — end with --status transferred for cross-agent handoff
• parent chains — link sessions via --parent for continuity tracking

Projects

Projects scope memories and sessions. Register once, then auto-detect from working directory:

$ rememora project add myapp --path /path/to/myapp
$ cd /path/to/myapp
$ rememora context --auto  # auto-detects "myapp"

Categories

Tiered Loading

Rememora loads context at three detail levels to minimize token usage:

Search

Three search modes, composable:

• BM25 (default) — SQLite FTS5 full-text search, zero dependencies
• Vector (feature-gated) — cosine similarity via sqlite-vec + all-MiniLM-L6-v2
• Hybrid RRF — reciprocal rank fusion merging BM25 + vector results with k=60

Hotness Scoring

Memories are ranked by a blend of importance and hotness:

frequency  = sigmoid(log1p(access_count))   // S-curve 0→1
recency   = exp(-age_days / 7.0)            // 7-day half-life
hotness   = frequency * recency              // combined score
final     = 0.7 * importance + 0.3 * hotness  // blended rank

save

Save a memory to the database.

rememora save "<content>" \
    --category <preference|entity|decision|event|case|pattern> \
    --project <name> \
    --importance <0.0-1.0> \
    --tags "tag1,tag2" \
    --name "optional display name"

search

Search memories using BM25 full-text search (or hybrid with vector if enabled).

rememora search "<query>" \
    --project <name> \
    --category <category> \
    --limit <n> \
    --json

context

Load full project context — memories, last session, working state. The primary entry point for agents at session start.

rememora context --project <name>    # explicit project
rememora context --auto              # auto-detect from CWD
rememora context --auto --cheatsheet  # compact top-5 summary

session

Manage agent sessions with full lifecycle tracking.

# Start a new session
rememora session start --agent claude-code --project myapp \
    --intent "implementing auth" --parent <prev-id>

# End a session
rememora session end <id> \
    --summary "Auth complete" \
    --working-state "Need biometric auth"

# Transfer to another agent
rememora session end <id> --status transferred \
    --summary "..." --working-state "..."

# End active session (hook-friendly)
rememora session end-active --project myapp

# Show last session for project
rememora session resume --project myapp

# List recent sessions
rememora session list --project myapp --limit 10

project

Manage project registrations.

rememora project add <name> --path <dir> --description "..." --stack "..."
rememora project list
rememora project show <name>

get

Retrieve a specific context by URI.

rememora get "rememora://projects/myapp/memories/decision/zustand"

supersede

Mark a memory as replaced by a new one (soft delete with audit trail).

rememora supersede --old <uri-or-id> --new <uri-or-id>

relate

Create bidirectional links between memories.

rememora relate --source <uri> --target <uri> \
    --relation <related|depends_on|derived_from|supersedes> \
    --reason "why they're linked"

extract

Extract memories from text using LLM (requires ANTHROPIC_API_KEY).

# Extract and preview
echo "We chose SQLite because..." | rememora extract

# Extract and save directly
echo "..." | rememora extract --save --project myapp

curate

Autonomous memory extraction from Claude Code session transcripts.

rememora curate --auto                      # auto-discover all sessions
rememora curate --file <path.jsonl>           # specific file
rememora curate --auto --dry-run             # preview only
rememora curate --auto --reset-watermark     # re-curate from start
cat transcript.txt | rememora curate --from-stdin --project myapp

evolve

LLM-driven memory consolidation — finds similar clusters and merges/supersedes/prunes.

rememora evolve --project myapp             # run consolidation
rememora evolve --project myapp --dry-run   # preview clusters

consolidate

Smart deduplication with dual gate (24h age + 5 new memories threshold).

rememora consolidate --project myapp
rememora consolidate --project myapp --check-only  # check gate only

setup

Auto-detect and configure agents to use Rememora.

rememora setup            # dry-run: show what would be changed
rememora setup --apply   # apply configuration

agent-run

Dispatch a GitHub issue to Claude CLI with quality gates.

rememora agent-run --repo owner/repo --issue 42 --retries 3

Workflow: Fetch issue → Move to "In Progress" → Create worktree → Run Claude CLI → Quality gate (tests) → Open PR → Move to "Ready for Review"

agent-loop

Continuous polling of GitHub project board for automated issue dispatch.

rememora agent-loop --repo owner/repo --poll 300   # poll every 5m
rememora agent-loop --repo owner/repo --once       # one-shot

encrypt / decrypt

Convert between encrypted (SQLCipher) and plaintext databases.

rememora encrypt   # encrypt existing plaintext DB
rememora decrypt   # decrypt to plaintext

export

Export memories as JSON or markdown.

rememora export --project myapp --format json
rememora export --project myapp --format markdown

status

Show database statistics — memory counts, categories, sessions, curator info.

$ rememora status
  Database: ~/.rememora/rememora.db (encrypted)
  Memories: 142 active, 23 superseded
  Categories: 31 decision, 28 entity, 25 pattern...
  Sessions: 67 total, 12 transferred
  Last curated: 2h ago (4 added)

tui

Interactive terminal dashboard for browsing memories, sessions, and projects.

rememora tui

Built with ratatui. Navigate with keyboard: Tab to switch panes, / to search, j/k to scroll.

eval

Database compliance metrics — checks session hygiene, memory quality, transfer chains.

rememora eval

URI Scheme

All contexts are addressable via hierarchical URIs:

rememora://global/memories/{category}/{slug}
rememora://projects/{name}/memories/{category}/{slug}
rememora://projects/{name}/_meta
rememora://agents/{name}/...
rememora://sessions/{id}/...

Database Schema

Single SQLite database at ~/.rememora/rememora.db with WAL mode.

Key Tables

Curation Pipeline

The autonomous curation pipeline processes Claude Code session transcripts in four stages:

1. JSONL Parsing — reads session files incrementally via byte-offset watermarks (never re-processes old content)
2. Signal Gate (Haiku) — fast YES/NO classification: "Does this transcript contain memorable knowledge?" (~$0.03 per call)
3. AUDN Curation (Sonnet) — full Add/Update/Delete/Noop cycle via a subagent with Bash access to rememora save/search/supersede
4. Consolidation — if gate conditions are met (24h + 5 new memories), triggers smart dedup via evolve

Claude Code Plugin

Full integration with Claude Code via hooks and skills:

Hooks (automatic)

Skills (model-invoked)

Agent Orchestration

The agent-run and agent-loop commands provide autonomous issue dispatch:

1. Fetch issue from GitHub → move to "In Progress" on project board
2. Create isolated git worktree under .agents/worktrees/
3. Run Claude CLI with issue context + rememora memory
4. Quality gate: run cargo test, retry on failure (configurable)
5. Open pull request → move to "Ready for Review"
6. agent-loop also merges "Cherry-Picked" PRs automatically

Encryption

Rememora uses SQLCipher for encryption at rest. Key sources (in priority order):

1. REMEMORA_KEY environment variable (hex string)
2. macOS Keychain / Linux secret-service
3. Interactive password prompt (via rpassword)

Use --no-encryption flag for development/testing.

Vector Search

Optional feature-gated vector search using:

• Model: all-MiniLM-L6-v2 (384-dim, ~1.3MB, downloaded from HuggingFace on first use)
• Backend: Candle with Metal GPU acceleration on Apple Silicon
• Index: sqlite-vec for KNN queries with cosine distance metric
• Hybrid: Reciprocal Rank Fusion (RRF) with k=60 merges BM25 + vector results

Enable with: cargo install --path . --features embed-candle,metal

Configuration

Environment Variables

Database Location

Default: ~/.rememora/rememora.db

Global Flags