Metadata-Version: 2.4
Name: remind-mcp
Version: 0.10.5
Summary: Generalization-capable memory layer for LLMs with episodic buffers, semantic graphs, and spreading activation retrieval
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.39.0
Requires-Dist: click>=8.1.0
Requires-Dist: fastmcp>=0.4.0
Requires-Dist: filelock>=3.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: numpy>=2.0.0
Requires-Dist: openai>=1.52.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: sqlite-vec>=0.1.6
Requires-Dist: starlette>=0.38.0
Requires-Dist: uvicorn>=0.30.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Provides-Extra: mysql
Requires-Dist: pymysql>=1.0; extra == 'mysql'
Provides-Extra: postgres
Requires-Dist: pgvector>=0.3.0; extra == 'postgres'
Requires-Dist: psycopg[binary]>=3.0; extra == 'postgres'
Provides-Extra: rerank
Requires-Dist: sentence-transformers>=3.0.0; extra == 'rerank'
Description-Content-Type: text/markdown

# Remind

[![PyPI version](https://img.shields.io/pypi/v/remind-mcp.svg)](https://pypi.org/project/remind-mcp/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

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](https://sandst1.github.io/remind/)** · **[Examples](https://sandst1.github.io/remind/examples/)** · **[Changelog](https://sandst1.github.io/remind/reference/changelog)**

## Quick start

```bash
pip install remind-mcp
```

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

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

Use it:

```bash
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`.

```bash
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.):

```bash
remind-mcp --port 8765
```

```json
{
  "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:

```bash
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:

```bash
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](https://sandst1.github.io/remind/guide/configuration.html#vector-search).

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

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

```bash
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/](examples/) directory for ready-to-run setups ([SQLite](examples/sqlite/), [PostgreSQL + Docker](examples/postgres-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](https://sandst1.github.io/remind/)**:

- [What is Remind?](https://sandst1.github.io/remind/guide/what-is-remind) — How it works, how it differs from RAG
- [Skills + CLI](https://sandst1.github.io/remind/guide/skills) — The recommended integration path
- [Configuration](https://sandst1.github.io/remind/guide/configuration) — Providers, config file, env vars
- [Core Concepts](https://sandst1.github.io/remind/concepts/episodes) — Episodes, consolidation, concepts, entities, relations
- [Examples](https://sandst1.github.io/remind/examples/) — Project memory, sparring partner, research ingestion
- [CLI Reference](https://sandst1.github.io/remind/reference/cli-commands) — All commands
- [MCP Tools](https://sandst1.github.io/remind/reference/mcp-tools) — MCP tool reference

## License

Apache 2.0 ([LICENSE](./LICENSE))
