remind: Instructions file for Codex

Remind - Development Guide for AI Agents

This guide is for AI agents developing Remind itself. For using Remind as a memory layer, see docs/AGENTS.md.

Project Overview

Remind is an agent-driven memory layer for LLMs. It provides temporal facts, semantic retrieval, and structured curation — the calling agent is the only intelligence. There are no internal LLM calls.

Core architecture: Episodes → Agent curation via apply → Concepts with relations

Architecture

src/remind/
├── models.py          # Data models (Concept, Episode, Entity, Relation, Fact, Conflict)
├── store.py           # SQL persistence and disposable query projection
├── file_store.py      # Default JSON store, write journal, recovery, migration
├── serialization.py   # Complete portable snapshots and backups
├── operations.py      # Revision checks and idempotency
├── evals.py           # Operational, semantic, and external-agent evaluations
├── interface.py       # MemoryInterface - main public API
├── config.py          # Configuration loading (config file, env vars, defaults)
├── facts.py           # Deterministic fact processing (clustering, collision detection)
├── apply.py           # Batch write engine (op vocabulary, transaction support)
├── snapshot.py        # Batch read engine (combinable scopes)
├── retrieval.py       # Spreading activation retrieval
├── reranker.py        # Optional cross-encoder reranking (requires [rerank] extra)
├── cli.py             # Command-line interface (project-aware)
├── mcp_server.py      # MCP (Model Context Protocol) server
├── background.py      # Background recall worker spawning
├── background_worker.py # Subprocess entry point for recall worker
├── api/               # REST API for web UI
│   ├── __init__.py    # Exports api_routes
│   └── routes.py      # Starlette route handlers
├── static/            # Web UI assets (compiled)
│   ├── index.html     # Entry point
│   └── assets/        # CSS/JS bundles
├── skills/            # Bundled agent skills (installed via `remind skill-install`)
│   ├── remind-capture/  # When/how to write memories while working
│   ├── remind-context/  # When/how to recall before acting
│   └── remind-curate/   # Consolidation procedure, conflict triage, label upkeep
└── providers/         # Embedding provider implementations
    ├── base.py        # EmbeddingProvider ABC
    ├── local.py       # Local embeddings via fastembed (default)
    ├── openai.py      # OpenAI embeddings
    ├── azure_openai.py # Azure OpenAI embeddings
    └── ollama.py      # Ollama embeddings