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:

Creates a Fact row with validity tracking
Assigns it to a cluster based on entity overlap (Jaccard similarity)
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)

Name		Name	Last commit message	Last commit date
Latest commit History 239 Commits
.claude		.claude
.github/workflows		.github/workflows
.remind		.remind
docs		docs
examples		examples
src/remind		src/remind
tests		tests
web		web
website		website
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
TODO.md		TODO.md
discussion.md		discussion.md
docker-compose.yml		docker-compose.yml
memory.db		memory.db
pyproject.toml		pyproject.toml
remind.log		remind.log
uv.lock		uv.lock

Navigation Menu

Repository files navigation

Remind

Quick start

How it works

Two batch tools

`remind snapshot` — Read state

`remind events` — Poll the change feed

`remind apply` — Write changes

Agent skills

MCP Server

Key features

Embedding providers

Database backends

CLI reference

Documentation

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Remind

Quick start

How it works

Two batch tools

remind snapshot — Read state

remind events — Poll the change feed

remind apply — Write changes

Agent skills

MCP Server

Key features

Embedding providers

Database backends

CLI reference

Documentation

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`remind snapshot` — Read state

`remind events` — Poll the change feed

`remind apply` — Write changes