Remind

Agent-driven memory layer for LLMs. Remind is a deterministic memory substrate with temporal facts, semantic retrieval, and structured curation — the calling agent is the only intelligence.

Documentation · Examples · Changelog

Quick start

pip install remind-mcp

No configuration required — Remind uses local embeddings by default (fastembed, no API key).

remind remember "This project uses React with TypeScript"
remind remember "Chose PostgreSQL for the database" -t decision
remind remember "Cache TTL is 600 seconds" -t fact -e concept:caching
remind recall "What tech stack are we using?"

How it works

Remind stores episodes (raw experiences) and concepts (generalized knowledge). You capture and curate memories explicitly using CLI commands or MCP tools.

For facts (-t fact), Remind automatically:

1. Creates a Fact row with validity tracking
2. Assigns it to a cluster based on entity overlap (Jaccard similarity)
3. Detects potential collisions with existing facts — same-cluster collisions and cross-cluster related facts are returned with ready-to-paste apply commands

For any remember call, the output also surfaces the top-5 nearest episodes and concepts semantically, so you can catch contradictions before they go unnoticed.

For patterns and concepts, you use remind apply to create them from episodes:

remind apply << 'EOF'
concept from=ep:11,ep:12 title="Retry-with-backoff for resilience" "Exponential backoff resolves flaky deploys and API timeouts."
processed ids=ep:11,ep:12
EOF

Two batch tools

remind snapshot — Read state

remind snapshot stats pending conflicts health        # Full overview
remind snapshot entity:concept:caching                # Everything about an entity
remind snapshot concept:abc123                        # Concept detail with history

# Browse scopes (for exploring memory)
remind snapshot concepts                              # All concepts
remind snapshot episodes:20                           # Recent 20 episodes
remind snapshot entities:person                       # Entities filtered by type
remind snapshot labels                                # All labels with counts
remind snapshot decisions questions                   # Episodes by type
remind snapshot bootstrap                              # Query-free stable context

Returns JSON. Combinable scopes:

Scope	Description
pending	Unprocessed episodes with their entities
conflicts[:<status>]	Open conflicts (or resolved/dismissed/all)
health	Actionable issues: pending episodes, open conflicts, orphan concepts
stats	Memory statistics
concepts[:<n>]	All concepts (default 50)
episodes[:<n>]	Recent episodes (default 20)
entities[:<type>]	All entities with mention counts, filterable by type
labels	All distinct key/value labels in use, with counts
decisions[:<n>]	Recent decision episodes
questions[:<n>]	Recent question episodes
entity:<id>	Episodes and concepts for a specific entity
label:<key>=<value>	All episodes and concepts carrying a label
concept:<id>	Concept detail with facts and supersession history
recent:<n>	N most recent episodes
query:<text>	Semantic search results
events[:<since_seq>]	Change-feed events with seq > since_seq (default 0). Prefer remind events.
bootstrap[:<n>]	Query-free stable context: top-n actionable concepts by confidence + open conflicts + stats (default 10)

remind events — Poll the change feed

remind events                    # All events from the start
remind events --since 42         # Only events after seq 42
remind events --kind conflict_opened --since 42

Every write (remember, supersede, conflict, resolve, dismiss, concept, update, label, unlabel, delete, restore, processed) appends an append-only row atomically with the write it describes. Returns {since_seq, count, events, next_since_seq} — pass next_since_seq back in as --since on the next poll instead of re-scanning snapshot pending.

remind apply — Write changes

remind apply << 'EOF'
remember as=f1 t=fact e=concept:cache "Cache TTL is 600 seconds"
supersede old=fact:old123 new=$f1
concept as=c1 from=ep:1,ep:2 title="Pattern name" "Summary"
evidence concept=$c1 episode=ep:3 type=supports strength=0.8 "confirms pattern"
resolve id=conflict:7 winner=fact:abc "confirmed by alice"
processed ids=ep:1,ep:2
EOF

All operations run in a single transaction. --dry-run validates without executing.

Operations:

Op	Description
remember	Store episode (same params as CLI remember)
supersede old=<fact> new=<fact>	Replace old fact — auto-records resolved conflict
conflict fact_a=<id> fact_b=<id>	Flag contradiction for triage
resolve id=<conflict> winner=<fact>	Resolve conflict; losing fact is superseded
dismiss id=<conflict>	Dismiss conflict (both facts stay active)
concept from=<eps> title="..." "summary"	Create concept from episodes
link from=<concept> to=<concept> type=<relation>	Add concept relation
evidence concept=<id> episode=<id> type=<supports|contradicts|qualifies>	Link episode evidence to concept
unlink concept=<id> episode=<id>	Remove evidence link
entity_relation source=<id> target=<id> relation=<type>	Create entity graph edge
reshape id=<concept> type=<new_type>	Change concept type
merge from=<id1>,<id2> into=<new_id>	Combine overlapping concepts
split id=<concept> into=<id1>,<id2>	Separate distinct concerns
update id=<id> [field=value...]	Update episode or concept fields
label id=<id> key=<key> value=<value>	Add a key=value label to episode/concept
unlabel id=<id> key=<key> value=<value>	Remove a key=value label from episode/concept
delete id=<id> / restore id=<id>	Soft delete / restore
processed ids=<ep1>,<ep2>	Mark episodes as reviewed

Agent skills

Install skills to teach AI agents how to use Remind:

remind skill-install

Three skills:

• remind-capture — When and how to write memories (includes decision tree and entity type guide)
• remind-context — When and how to recall before acting (includes output interpretation guide)
• remind-curate — How to process pending episodes into concepts, resolve conflicts, maintain quality

MCP Server

For IDE agents (Cursor, Claude Desktop, etc.):

remind-mcp --port 8765

{
  "mcpServers": {
    "remind": {
      "url": "http://127.0.0.1:8765/sse?db=my-project"
    }
  }
}

Tools: remember, recall, snapshot, apply, plus conflict/entity management.

Web UI at http://127.0.0.1:8765/ui/, REST API at /api/v1/.

Key features

• Zero-config embeddings — Local fastembed by default (no API key required)
• Labels as a substrate primitive — Freeform key=value tags on episodes/concepts, pushed down as a pre-filter into vector search (recall -l key=value), not just a post-filter
• Change feed — Append-only events table written atomically with every write; poll with remind events --since <seq> instead of re-scanning pending state
• Query-free bootstrap read — snapshot bootstrap returns deterministic, stable context (top concepts + conflicts + stats) with no embedding call, cheap enough to inject every turn
• Temporal facts — Validity windows, structural supersession, time-travel queries (--as-of)
• Collision detection — Same-cluster and cross-cluster collisions reported on write with ready-to-paste apply commands
• Nearby surfacing — Every remember call returns the top-k semantically nearest episodes and concepts for immediate conflict triage
• Evidence-weighted retrieval — Episodes link to concepts with typed relationships (supports, contradicts, qualifies); more evidence = higher recall rank
• Freeform concept types — Concepts can have any type string: pattern, rule, procedure, hypothesis, or any domain-specific label
• Concept evolution — reshape (change type), merge (combine overlapping), split (separate concerns), all with lineage tracking
• Transactional writes — apply runs all operations atomically
• Spreading activation retrieval — Queries activate related concepts through the knowledge graph
• Native vector indexes — sqlite-vec (SQLite), pgvector (PostgreSQL)
• Entity graph — Files, functions, people, tools linked to episodes and concepts via entity_relation
• Memory decay — Rarely-recalled concepts fade
• Soft delete / restore — With permanent purge as a separate step
• Web UI — Dashboard, concept graph, entity explorer

Embedding providers

Local embedding is the default (384-dim all-MiniLM-L6-v2). For cloud embeddings:

pip install "remind-mcp[openai]"   # OpenAI embeddings
pip install "remind-mcp[rerank]"   # Cross-encoder reranking

{
  "embedding_provider": "openai",
  "openai": { "api_key": "sk-..." }
}

Database backends

SQLite is the default. For PostgreSQL or MySQL:

pip install "remind-mcp[postgres]"   # PostgreSQL (psycopg v3 + pgvector)
pip install "remind-mcp[mysql]"      # MySQL (PyMySQL)

export REMIND_DB_URL="postgresql+psycopg://user:pass@localhost:5432/mydb"

CLI reference

Core
  remember     Add an episode (-t type, -e entity, -l key=value label, --asserted-by, --source-ref)
  recall       Semantic or entity-based retrieval (-k, --episode-k, -l label filter, --as-of)
  snapshot     Read memory state as JSON (combinable scopes)
  apply        Apply a batch changeset transactionally

Inspection
  inspect      List or detail concepts; use --episodes for episodes
  stats        Memory statistics
  entities     List entities or show details

Episode types
  decisions    Show decision episodes
  questions    Show open question episodes

Conflicts
  conflicts list/resolve/dismiss

Editing
  update-episode/update-concept
  delete-episode/restore-episode/purge-episode
  delete-concept/restore-concept/purge-concept

Embeddings
  embed-episodes  Backfill embeddings
  re-embed        Recompute embeddings (--episodes/--concepts/--entities/--all)

Import / Export
  export/import

Skills
  skill-install  Install Remind skills

UI
  ui           Launch the web UI

Entity types: file, function, class, module, subject, person, project, tool — format is type:name (e.g., file:src/auth.ts, person:alice, tool:redis, concept:caching)

Documentation

Full documentation at sandst1.github.io/remind:

• What is Remind? — How it works
• Skills + CLI — Agent integration
• Configuration — Providers, config
• CLI Reference — All commands
• MCP Tools — MCP reference

License

Apache 2.0 (LICENSE)