Remind

Generalization-capable memory layer for LLMs. Unlike simple RAG systems that store verbatim text, Remind extracts and maintains generalized concepts from experiences — mimicking how human memory consolidates specific events into abstract knowledge.

Documentation · Examples · Changelog

Quick start

pip install remind-mcp

Configure a provider (~/.remind/remind.config.json):

{
  "llm_provider": "anthropic",
  "embedding_provider": "openai",
  "anthropic": { "api_key": "sk-ant-..." },
  "openai": { "api_key": "sk-..." }
}

Use it:

remind remember "This project uses React with TypeScript"
remind remember "Chose PostgreSQL for the database" -t decision
remind consolidate
remind recall "What tech stack are we using?"

Episodes go in, consolidation runs, generalized concepts come out.

Two ways to use Remind

Skills + CLI (recommended)

Project-local memory via composable skills. The database lives in your repo at .remind/remind.db.

remind skill-install                    # Install the remind skill
remind remember "..."                   # Store experiences
remind recall "..."                     # Retrieve memories
remind end-session                      # Consolidate at end of session

Skills are Markdown files read by AI agents (Claude Code, Cursor, etc.) — they teach the agent how to use Remind as a memory layer for your project.

MCP Server

Centralized memory for IDE agents (Cursor, Claude Desktop, etc.):

remind-mcp --port 8765

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

The MCP server also serves a web UI at http://127.0.0.1:8765/ui/ and a REST API at /api/v1/.

You can also launch the UI directly from the CLI against the current project's database:

remind ui

Key features

• Dual-track concepts — Pattern concepts for generalizations, fact clusters for verbatim details. Facts are never abstracted away.
• Generalization — Episodes are consolidated into concepts with confidence, conditions, and exceptions
• Auto-ingest — Stream raw conversation text; an LLM triage pass extracts memory-worthy episodes (optional density score is diagnostic only, not a gate)
• Spreading activation retrieval — Queries activate related concepts through the knowledge graph, with hybrid embedding+keyword scoring and optional cross-encoder reranking
• Native vector indexes — sqlite-vec for SQLite, pgvector for PostgreSQL; automatic fallback to brute-force when unavailable
• Entity graph — Files, functions, people, tools and other entities are extracted and linked to episodes and concepts
• Outcome tracking — Record action-result pairs; consolidation extracts causal strategy patterns
• Soft delete / restore — Episodes and concepts can be deleted and restored; permanent purge is a separate step
• Memory decay — Rarely-recalled concepts fade; frequently-used ones stay sharp
• Composable via Skills — Build any workflow on top of the remind CLI
• Debug logging — Enable logging_enabled to get full LLM prompt/response logs in remind.log next to the database
• Multi-provider — Anthropic, OpenAI, Azure OpenAI, Ollama (fully local)
• Web UI — Dashboard, concept graph, entity explorer

Database backends

SQLite is the default with sqlite-vec for native vector search (included as a dependency). For PostgreSQL or MySQL, install the corresponding extra:

pip install "remind-mcp[postgres]"   # PostgreSQL (psycopg v3 + pgvector)
pip install "remind-mcp[mysql]"      # MySQL (PyMySQL)
pip install "remind-mcp[rerank]"     # Cross-encoder reranking (sentence-transformers)

PostgreSQL installations get pgvector for HNSW-indexed vector search. Enable the extension with CREATE EXTENSION vector (Remind does this automatically).

SQLite note: sqlite-vec only activates if your Python build supports SQLite extension loading (enable_load_extension). Some macOS/pyenv Pythons do not; Remind then falls back to in-process similarity. See Configuration — Vector search.

Point Remind at your database via config file, environment variable, or CLI flag:

{ "db_url": "postgresql+psycopg://user:pass@localhost:5432/mydb" }

export REMIND_DB_URL="postgresql+psycopg://user:pass@localhost:5432/mydb"
remind --db "postgresql+psycopg://user:pass@localhost:5432/mydb" remember "..."

Remind creates the schema automatically on first use. See the examples/ directory for ready-to-run setups (SQLite, PostgreSQL + Docker).

CLI reference

Core
  remember     Add an episode (-t type, -e entity, -m metadata, --no-embed)
  recall       Semantic or entity-based memory retrieval (-k, --episode-k)
  ingest       Auto-ingest raw text (LLM triage; optional diagnostic density score)
  flush-ingest Force-flush the ingestion buffer
  consolidate  Run consolidation manually (--background, --force)
  reconsolidate  Reset derived data and re-consolidate from scratch
  end-session  Flush ingest buffer, then consolidate in background

Inspection
  inspect      List or detail concepts; use --episodes for episodes
  stats        Memory statistics and decay info
  status       Processing status (workers, queues, pending)
  types        Show configured episode types for this environment
  search       Keyword/tag search across concepts
  entities     List entities or show a specific entity
  mentions     All episodes mentioning an entity
  entity-relations  Relationships between entities

Episode types
  decisions    Show decision episodes
  questions    Show open question episodes

Topics
  topics list       List topics with stats (--json / --compact-json)
  topics create     Create a topic (--description)
  topics update     Rename or update description
  topics delete     Delete an empty topic
  topics overview   Top concepts for a topic (-k)

Editing
  update-episode      Update content, type, entities, or topic (--topic, --clear-topic)
  update-concept      Update title, summary, confidence, tags, relations, or topic (--topic, --clear-topic)
  extract-relations   Backfill entity relationships from existing episodes

Soft delete / restore
  delete-episode   Soft delete an episode
  restore-episode  Restore a soft-deleted episode
  purge-episode    Permanently delete an episode

  delete-concept   Soft delete a concept
  restore-concept  Restore a soft-deleted concept
  purge-concept    Permanently delete a concept

  deleted          List all soft-deleted items
  purge-all        Permanently delete all soft-deleted items

Embeddings
  embed-episodes  Backfill embeddings for older episodes (--batch-size)
  re-embed        Recompute episode/concept embeddings for model or dimension changes (--episodes/--concepts/--all)

Import / Export
  export       Export memory to JSON
  import       Import memory from JSON

Skills
  skill-install  Install Remind skills into .claude/skills/

UI
  ui           Launch the web UI (auto-opens browser)

Documentation

Full documentation at sandst1.github.io/remind:

• What is Remind? — How it works, how it differs from RAG
• Skills + CLI — The recommended integration path
• Configuration — Providers, config file, env vars
• Core Concepts — Episodes, consolidation, concepts, entities, relations
• Examples — Project memory, sparring partner, research ingestion
• CLI Reference — All commands
• MCP Tools — MCP tool reference

License

Apache 2.0 (LICENSE)