Configuration

Environment variables

Variable	Default	Description
MEM7_DIR	~/.mem7	Data directory (hosts workspace/ and index.db)
MEM7_LISTEN	:9070	HTTP bind address in serve mode. In stdio mode, the address probed for a running daemon to auto-proxy to (localhost:9070)
MEM7_TOKEN	(empty)	Bearer token for /rpc, /mcp, /sse and /memory/*; also what lets a request speak for an agent
MEM7_SCOPES	(empty)	JSON file of read scopes per agent; empty = reads not scoped
MEM7_CHAIN_KEY	(empty)	Key of the workspace's hash chain (HMAC-SHA256); empty = SHA-256
MEM7_CHAIN_KEYS_RETIRED	(empty)	Earlier chain keys, comma-separated: they verify the stretches before a mem7 rekey, never seal
MEM7_MAX_ENTRIES	10000	Soft ceiling on live entries
MEM7_EMBED_URL	(empty)	Embedding provider base URL. Enables hybrid search
MEM7_EMBED_MODEL	nomic-embed-text	Model name for the embedding API
MEM7_EMBED_PROVIDER	ollama	ollama (POST /api/embed) or openai (POST /v1/embeddings)
MEM7_EMBED_KEY	(empty)	Bearer token for the embedding API
MEM7_RERANK_URL	(empty)	Reranking LLM base URL. Enables LLM reranking after RRF merge
MEM7_RERANK_MODEL	gemma4:e4b	Model name for the Ollama generate API

Flags on mem7 serve mirror MEM7_LISTEN and MEM7_TOKEN:

mem7 serve --listen :9070 --token mem7_secret123

Maintenance commands:

mem7 rescan    # rebuild index.db from the markdown workspace
mem7 prune     # drop TTL-expired entries

A systemd unit for daemon mode ships in contrib/systemd/mem7.service.

Hybrid search

Hybrid search is entirely opt-in. Without MEM7_EMBED_URL, mem7 uses pure BM25.

When enabled, memory_store computes and persists an embedding alongside each entry. memory_search retrieves BM25 top-2N and cosine top-2N candidates, then merges them via Reciprocal Rank Fusion (RRF, k=60) into the final top-N. Embeddings are stored as BLOBs in SQLite and cached in memory for sub-ms cosine search.

With local Ollama

MEM7_EMBED_URL=http://localhost:11434 \
MEM7_EMBED_MODEL=nomic-embed-text \
  mem7 serve --listen :9070

With OpenAI API

MEM7_EMBED_URL=https://api.openai.com \
MEM7_EMBED_MODEL=text-embedding-3-small \
MEM7_EMBED_PROVIDER=openai \
MEM7_EMBED_KEY=sk-... \
  mem7 serve --listen :9070

With any OpenAI-compatible endpoint

vLLM, LiteLLM, Azure OpenAI, etc.:

MEM7_EMBED_URL=http://localhost:8000 \
MEM7_EMBED_MODEL=BAAI/bge-small-en-v1.5 \
MEM7_EMBED_PROVIDER=openai \
  mem7 serve --listen :9070

LLM reranking

Reranking is opt-in, with or without embeddings. It over-fetches 3x candidates (merged via RRF when hybrid search is on, BM25 alone otherwise), then uses an LLM to score relevance before returning the final top-N. It falls back to non-reranked results if the LLM is unavailable.

MEM7_EMBED_URL=http://localhost:11434 \
MEM7_RERANK_URL=http://localhost:11434 \
MEM7_RERANK_MODEL=gemma4:e4b \
  mem7 serve --listen :9070

Workspace layout

~/.mem7/
├── workspace/
│   ├── MEMORY.md                      # reserved for long-term notes
│   └── memory/
│       ├── 2026-04-11.md              # append-only daily logs
│       └── 2026-04-12.md
└── index.db                           # SQLite (facts + facts_fts + embeddings)

The markdown files are the source of truth. index.db is a derived cache that can be dropped and rebuilt at any time via mem7 rescan.

Each entry is written as a level-2 heading followed by a fenced mem7 envelope and a free-form body:

## example_key

```mem7
op: store
agent: claude
tags: demo, example
created: 2026-04-11T20:00:00Z
updated: 2026-04-11T20:00:00Z
```

Free-form markdown content lives here.

---

Usage with flux7-mesh

In your mesh config.yaml:

mcp_servers:
  - name: memory
    transport: stdio
    command: /home/user/go/bin/mem7
    env:
      MEM7_DIR: /home/user/.mem7

flux7-mesh discovers the tools via tools/list. Grants and policies apply as usual.

To share memory across machines, run mem7 serve on one host and connect via SSE or HTTP JSON-RPC.