Skip to content
Back to search

remind

A memory layer for AI Agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sandst1--remind/badge.svg)](/listings/sandst1--remind)

HTML

<a href="/listings/sandst1--remind"><img src="/api/listings/sandst1--remind/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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?"

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 300 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Remind
  2. [![PyPI version](https://img.shields.io/pypi/v/remind-mcp.svg)](https://pypi.org/project/remind-mcp/)
  3. [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
  4. [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
  5. 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.
  6. **[Documentation](https://sandst1.github.io/remind/)** · **[Examples](https://sandst1.github.io/remind/examples/)** · **[Changelog](https://sandst1.github.io/remind/reference/changelog)**
  7. ![Remind Architecture](docs/architecture.png)
  8. ## Quick start
  9. ```bash
  10. pip install remind-mcp
  11. ```
  12. **No configuration required** — Remind uses local embeddings by default (fastembed, no API key).
  13. ```bash
  14. remind remember "This project uses React with TypeScript"
  15. remind remember "Chose PostgreSQL for the database" -t decision
  16. remind remember "Cache TTL is 600 seconds" -t fact -e concept:caching
  17. remind recall "What tech stack are we using?"
  18. ```
  19. ## Durable local memory
  20. Local memory is stored as deterministic JSON records in `.remind/memory/`. Commit those files with the code; memories follow branch checkout and merge normally. `.remind/cache/` and `.remind/runtime/` hold ignored indexes, embeddings, logs, and recovery data. Existing local databases migrate automatically with a retained backup. Explicit `sqlite://`, PostgreSQL, and MySQL URLs continue selecting SQL directly.
  21. ```bash
  22. remind --store ./my-memory remember "User prefers concise answers"
  23. remind remember "Cache TTL is 600 seconds" -t fact --json --idempotency-key ttl-change
  24. remind recall "cache configuration" --json --explain
  25. remind doctor
  26. remind export memory.json # complete portable knowledge
  27. remind export backup.json --mode backup # also include embeddings and usage
  28. ```
  29. Edits now require revisions from `snapshot`; CLI apply accepts `--revisions '{"<id>":"<revision>"}'`, MCP/Python apply accepts `expected_revisions`. Read-only recall returns a structured `RecallResult` in Python; use `.text` for prompt context. [Storage and migration](https://sandst1.github.io/remind/concepts/storage) describes the breaking changes.
  30. Local evaluations cover capture → curation → restart → recall through Python, CLI, MCP, and REST. Run `remind-eval --suite operational`, `remind-eval --suite retrieval` (real local embeddings), or `remind-eval --suite agent --agent-command '<runner command>'`. See [evals/README.md](evals/README.md) for datasets, gates, and the external runner contract. No internal LLM calls or CI are introduced.
  31. ## How it works
  32. Remind stores **episodes** (raw experiences) and **concepts** (generalized knowledge). You capture and curate memories explicitly using CLI commands or MCP tools.
  33. For **facts** (`-t fact`), Remind automatically:
  34. 1. Creates a `Fact` row with validity tracking
  35. 2. Assigns it to a cluster based on entity overlap (Jaccard similarity)
  36. 3. Detects potential collisions with existing facts — same-cluster collisions and cross-cluster related facts are returned with ready-to-paste `apply` commands
  37. 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.
  38. For **patterns and concepts**, you use `remind apply` to create them from episodes:
  39. ```bash
  40. remind apply --revisions '<ID-to-revision JSON from snapshot>' << 'EOF'
  41. concept from=ep:11,ep:12 title="Retry-with-backoff for resilience" "Exponential backoff resolves flaky deploys and API timeouts."
  42. processed ids=ep:11,ep:12
  43. EOF
  44. ```
  45. ## Two batch tools
  46. ### `remind snapshot` — Read state
  47. ```bash
  48. remind snapshot stats pending conflicts health # Full overview
  49. remind snapshot entity:concept:caching # Everything about an entity
  50. remind snapshot concept:abc123 # Concept detail with history
  51. # Browse scopes (for exploring memory)
  52. remind snapshot concepts # All concepts
  53. remind snapshot episodes:20 # Recent 20 episodes
  54. remind snapshot entities:person # Entities filtered by type
  55. remind snapshot labels # All labels with counts
  56. remind snapshot decisions questions # Episodes by type
  57. remind snapshot bootstrap # Query-free stable context
  58. ```
  59. Returns JSON. Combinable scopes:
  60. | Scope | Description |
  61. |-------|-------------|
  62. | `pending` | Unprocessed episodes with their entities |
  63. | `conflicts[:<status>]` | Open conflicts (or `resolved`/`dismissed`/`all`) |
  64. | `health` | Actionable issues: pending episodes, open conflicts, orphan concepts |
  65. | `stats` | Memory statistics |
  66. | `concepts[:<n>]` | All concepts (default 50) |
  67. | `episodes[:<n>]` | Recent episodes (default 20) |
  68. | `entities[:<type>]` | All entities with mention counts, filterable by type |
  69. | `labels` | All distinct key/value labels in use, with counts |
  70. | `decisions[:<n>]` | Recent decision episodes |
  71. | `questions[:<n>]` | Recent question episodes |
  72. | `entity:<id>` | Episodes and concepts for a specific entity |
  73. | `label:<key>=<value>` | All episodes and concepts carrying a label |
  74. | `concept:<id>` | Concept detail with facts and supersession history |
  75. | `recent:<n>` | N most recent episodes |
  76. | `query:<text>` | Semantic search results |
  77. | `events[:<since_seq>]` | Change-feed events with `seq > since_seq` (default 0). Prefer `remind events`. |
  78. | `bootstrap[:<n>]` | Query-free stable context: top-n actionable concepts by confidence + open conflicts + stats (default 10) |
  79. ### `remind events` — Poll the change feed
  80. ```bash
  81. remind events # All events from the start
  82. remind events --since 42 # Only events after seq 42
  83. remind events --kind conflict_opened --since 42
  84. ```
  85. 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`.
  86. ### `remind apply` — Write changes
  87. ```bash
  88. remind apply << 'EOF'
  89. remember as=f1 t=fact e=concept:cache "Cache TTL is 600 seconds"
  90. supersede old=fact:old123 new=$f1
  91. concept as=c1 from=ep:1,ep:2 title="Pattern name" "Summary"
  92. evidence concept=$c1 episode=ep:3 type=supports strength=0.8 "confirms pattern"
  93. resolve id=conflict:7 winner=fact:abc "confirmed by alice"
  94. processed ids=ep:1,ep:2
  95. EOF
  96. ```
  97. All operations run in a single transaction. `--dry-run` validates without executing.
  98. **Operations:**
  99. | Op | Description |
  100. |----|-------------|
  101. | `remember` | Store episode (same params as CLI `remember`) |
  102. | `supersede old=<fact> new=<fact>` | Replace old fact — auto-records resolved conflict |
  103. | `conflict fact_a=<id> fact_b=<id>` | Flag contradiction for triage |
  104. | `resolve id=<conflict> winner=<fact>` | Resolve conflict; losing fact is superseded |
  105. | `dismiss id=<conflict>` | Dismiss conflict (both facts stay active) |
  106. | `concept from=<eps> title="..." "summary"` | Create concept from episodes |
  107. | `link from=<concept> to=<concept> type=<relation>` | Add concept relation |
  108. | `evidence concept=<id> episode=<id> type=<supports\|contradicts\|qualifies>` | Link episode evidence to concept |
  109. | `unlink concept=<id> episode=<id>` | Remove evidence link |
  110. | `entity_relation source=<id> target=<id> relation=<type>` | Create entity graph edge |
  111. | `reshape id=<concept> type=<new_type>` | Change concept type |
  112. | `merge from=<id1>,<id2> into=<new_id>` | Combine overlapping concepts |
  113. | `split id=<concept> into=<id1>,<id2>` | Separate distinct concerns |
  114. | `update id=<id> [field=value...]` | Update episode or concept fields |
  115. | `label id=<id> key=<key> value=<value>` | Add a key=value label to episode/concept |
  116. | `unlabel id=<id> key=<key> value=<value>` | Remove a key=value label from episode/concept |
  117. | `delete id=<id>` / `restore id=<id>` | Soft delete / restore |
  118. | `processed ids=<ep1>,<ep2>` | Mark episodes as reviewed |
  119. ## Agent skills
  120. Install skills to teach AI agents how to use Remind:
  121. ```bash
  122. remind skill-install
  123. remind skill-install --agent claude # Use .claude/skills instead
  124. remind skill-install --dir ~ # Install into ~/.agents/skills
  125. remind skill-install --agent cursor --dir /path/to/project
  126. ```
  127. By default, skills go into `.agents/skills` under the current working directory.
  128. Use `--agent agents|claude|cursor|codex|opencode` to select a layout and `--dir`
  129. to choose any base folder. Codex uses `.agents/skills`; OpenCode uses
  130. `.opencode/skills` in projects and `.config/opencode/skills` when targeting home.
  131. Re-running the command overwrites installed skill files with the bundled versions.
  132. Three skills:
  133. - **remind-capture** — When and how to write memories (includes decision tree and entity type guide)
  134. - **remind-context** — When and how to recall before acting (includes output interpretation guide)
  135. - **remind-curate** — How to process pending episodes into concepts, resolve conflicts, maintain quality
  136. ## MCP Server
  137. For IDE agents (Cursor, Claude Desktop, etc.):
  138. ```bash
  139. remind-mcp --port 8765
  140. ```
  141. ```json
  142. {
  143. "mcpServers": {
  144. "remind": {
  145. "url": "http://127.0.0.1:8765/sse?db=my-project"
  146. }
  147. }
  148. }
  149. ```
  150. Tools: `remember`, `recall`, `snapshot`, `apply`, plus conflict/entity management.
  151. Web UI at `http://127.0.0.1:8765/ui/`, REST API at `/api/v1/`.
  152. ## Key features
  153. - **Zero-config embeddings** — Local fastembed by default (no API key required)
  154. - **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
  155. - **Change feed** — Append-only `events` table written atomically with every write; poll with `remind events --since <seq>` instead of re-scanning pending state
  156. - **Query-free bootstrap read** — `snapshot bootstrap` returns deterministic, stable context (top concepts + conflicts + stats) with no embedding call, cheap enough to inject every turn
  157. - **Temporal facts** — Validity windows, structural supersession, time-travel queries (`--as-of`)
  158. - **Collision detection** — Same-cluster and cross-cluster collisions reported on write with ready-to-paste `apply` commands
  159. - **Nearby surfacing** — Every `remember` call returns the top-k semantically nearest episodes and concepts for immediate conflict triage
  160. - **Evidence-weighted retrieval** — Episodes link to concepts with typed relationships (`supports`, `contradicts`, `qualifies`); more evidence = higher recall rank
  161. - **Freeform concept types** — Concepts can have any type string: `pattern`, `rule`, `procedure`, `hypothesis`, or any domain-specific label
  162. - **Concept evolution** — `reshape` (change type), `merge` (combine overlapping), `split` (separate concerns), all with lineage tracking
  163. - **Transactional writes** — `apply` runs all operations atomically
  164. - **Spreading activation retrieval** — Queries activate related concepts through the knowledge graph
  165. - **Native vector indexes** — sqlite-vec (SQLite), pgvector (PostgreSQL)
  166. - **Entity graph** — Files, functions, people, tools linked to episodes and concepts via `entity_relation`
  167. - **Memory decay** — Rarely-recalled concepts fade
  168. - **Soft delete / restore** — With permanent purge as a separate step
  169. - **Web UI** — Dashboard, concept graph, entity explorer
  170. ## Embedding providers
  171. Local embedding is the default (384-dim `all-MiniLM-L6-v2`). For cloud embeddings:
  172. ```bash
  173. pip install "remind-mcp[openai]" # OpenAI embeddings
  174. pip install "remind-mcp[rerank]" # Cross-encoder reranking
  175. ```
  176. ```json
  177. {
  178. "embedding_provider": "openai",
  179. "openai": { "api_key": "sk-..." }
  180. }
  181. ```
  182. ## Database backends
  183. Local JSON records are the default; SQLite is used for disposable indexes. Explicit SQL URLs select a database backend. For PostgreSQL or MySQL:
  184. ```bash
  185. pip install "remind-mcp[postgres]" # PostgreSQL (psycopg v3 + pgvector)
  186. pip install "remind-mcp[mysql]" # MySQL (PyMySQL)
  187. ```
  188. ```bash
  189. export REMIND_DB_URL="postgresql+psycopg://user:pass@localhost:5432/mydb"
  190. ```
  191. ## CLI reference
  192. ```
  193. Core
  194. remember Add an episode (-t type, -e entity, -l key=value label, --asserted-by, --source-ref)
  195. recall Semantic or entity-based retrieval (-k, --episode-k, -l label filter, --as-of)
  196. snapshot Read memory state as JSON (combinable scopes)
  197. apply Apply a batch changeset transactionally
  198. Inspection
  199. inspect List or detail concepts; use --episodes for episodes
  200. stats Memory statistics
  201. entities List entities or show details
  202. Episode types
  203. decisions Show decision episodes
  204. questions Show open question episodes
  205. Conflicts
  206. conflicts list/resolve/dismiss
  207. Editing
  208. update-episode/update-concept
  209. delete-episode/restore-episode/purge-episode
  210. delete-concept/restore-concept/purge-concept
  211. Embeddings
  212. embed-episodes Backfill embeddings
  213. re-embed Recompute embeddings (--episodes/--concepts/--entities/--all)
  214. Import / Export
  215. export/import
  216. Skills
  217. skill-install Install Remind skills
  218. UI
  219. ui Launch the web UI
  220. ```
  221. **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`)
  222. ## Documentation
  223. Full documentation at **[sandst1.github.io/remind](https://sandst1.github.io/remind/)**:
  224. - [What is Remind?](https://sandst1.github.io/remind/guide/what-is-remind) — How it works
  225. - [Skills + CLI](https://sandst1.github.io/remind/guide/skills) — Agent integration
  226. - [Configuration](https://sandst1.github.io/remind/guide/configuration) — Providers, config
  227. - [CLI Reference](https://sandst1.github.io/remind/reference/cli-commands) — All commands
  228. - [MCP Tools](https://sandst1.github.io/remind/reference/mcp-tools) — MCP reference
  229. ## License
  230. Apache 2.0 ([LICENSE](./LICENSE))

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.