How Remem Works

Remem 0.5 is a Go service on port 4545: the REST API, MCP endpoint (Streamable HTTP at /mcp), Pebble storage, indexes, and lifecycle jobs all run in one process. No external database, Qdrant, Postgres, or Redis dependency is required for the core.

For MCP clients that only speak stdio (Claude Desktop, Claude Code), remem-mcp is a small companion binary you run directly — it holds no data itself and forwards MCP tool calls to Remem over HTTP. Clients that speak Streamable HTTP can connect to /mcp directly.

Storage engine

Remem maintains its indexes alongside the corpus:

HNSW vector index

all-MiniLM-L6-v2 embeddings (384 dimensions) generated locally through the packaged ONNX runtime. No external embedding API is required. The vector index enables approximate nearest-neighbour search for semantic queries.

Relationship graph

A durable graph where nodes are memories and edges are typed connections (relationship_type: related_to, caused_by, part_of, references, contradicts, supports, similar_to, derived_from). Edges are written automatically by relationship discovery or explicitly through the connections API.

Ordered attributes

Ordered attributes support bounded listing, filtering, and time-windowed queries.

Text index

An inverted text index supports keyword search, hybrid retrieval, and tag filters.

Pebble storage

Pebble provides durable ordered storage for memory content and metadata. Synchronous commits are the reliability default, so acknowledged writes survive a process restart. Derived indexes can be rebuilt by remem-admin when an operator needs to repair or verify them.

Write path

store_memory(content, policy, ttl_seconds, tags, importance, emotional_valence, arousal)
    │
    ├─ embed(content) → 384-dim vector                [ONNX, in-process]
    ├─ write(payload) → Pebble                        [durable commit]
    ├─ arousal >= 0.8? → force-promote to long_term,
    │   floor importance at 0.9, set flashbulb_until   [flashbulb protection]
    └─ dispatch(auto-discovery) → background worker
              │
              ├─ query HNSW index (top-K similar memories)
              ├─ filter by auto_discovery_threshold (default: 0.7)
              └─ write connections → relationship graph

The API returns after the durable write. Relationship discovery is asynchronous, so store_memory does not wait for graph enrichment.

Read path

Semantic search:

1. Embed the query
2. Query the vector index for nearest memories
3. Return ranked results

Hybrid search:

1. Embed the query
2. Query the vector index (semantic score)
3. Query the text index (keyword score)
4. Combine semantic and keyword scores
5. Return ranked results

Graph traversal:

1. Start from a memory node
2. Walk outgoing edges in the relationship graph (breadth-first)
3. Return nodes at each depth level

Memory lifecycle

Stage	Trigger	Effect
Short-term	A short-retention policy + ttl_seconds	Expires automatically at the policy boundary
Long-term	policy: "long_term" or promotion	Persists subject to retention, decay, and forgetting
Promotion	Manual (promote_to_longterm / POST .../promote), or automatic at creation for flashbulb memories (arousal >= 0.8)	Short-term → long-term
Importance decay	Background task, daily	Long-term importance decrements ~0.5%/day; flashbulb memories exempt while protected
Active forgetting	Background task, daily	health decays (short-term −8/day, long-term −2/day since last recall); recall boosts health +10 (capped 100); memory is hard-deleted at health 0. Flashbulb memories exempt while protected
Archive	hard=false (default) on delete	Hidden from search, retained in storage
Delete	hard=true on delete	Removed from all indexes

Emotional memory & flashbulb protection

store_memory accepts emotional_valence (-1.0 to 1.0) and arousal (0.0 to 1.0). A memory created with arousal >= 0.8 becomes a flashbulb memory: it’s force-promoted to long_term, its importance is floored at 0.9, and it’s exempt from importance decay and active forgetting for 30 days (flashbulb_until). This only happens at creation time — raising arousal later via update_memory does not retroactively apply it. See Memory Lifecycle for details.

Background tasks

Lifecycle and repair work runs through durable background jobs inside Remem — no separate worker process is needed. Configure the scheduler and workers in remem.toml:

Task	Default interval
expire_short_term	5 minutes
apply_importance_decay	daily
active_forgetting	daily
consolidate_similar	weekly
cleanup_archived	monthly
discover_connections	hourly

See Configuration for the full [tasks] config, and Memory Lifecycle for what each task does.