mem-context — Temporal Memory MCP Server
Full-text search over past AI assistant sessions. Uses SQLite FTS5 with trigram
tokenizer + dual-pass CZ/EN query translation via Ollama. Stores complete session
texts, syncs via git shared repo across machines.
Why
AI assistants lose context between sessions. mem-context stores complete session
transcripts in SQLite FTS5 and retrieves relevant past context using full-text
search with BM25 ranking + vector re-rank. No lossy LLM extraction — search
operates on primary data.
Features
-
FTS5 full-text search — unicode61 tokenizer with prefix matching.
Dual-pass query: native language + Ollama EN translation. CamelCase,
snake_case, and underscore-split identifier handling.
-
Vector re-rank — BM25 recall (200 candidates) re-ranked by cosine
similarity via Ollama mxbai-embed-large (1024d).
-
Full session storage — complete transcripts indexed in SQLite FTS5.
No chunking, no lossy extraction. Session text is primary data.
-
Git-based sync — bidirectional sync via shared git repo.
{session_id}_{host_id}.yaml format — two machines never collide.
Full sync on startup, auto-export on remember().
-
User memories — remember() stores as mini-sessions in the same
FTS5 index with higher weight (0.7 vs 0.5 for auto-captures).
-
Weight decay — exponential decay per memory type.
Never reaches zero — only explicit forget() deactivates.
-
Automatic capture — hooks for Claude Code (Stop/SessionEnd)
and OpenCode. Detached subprocess, hash-based skip on re-import.
-
One-command provisioning — mem-context init detects AI tools,
registers MCP server, injects instructions, installs slash-command skills.
Installation
# 1. Install Ollama
curl -fsSL https://ollama.com/install.sh | sh
# 2. Install mem-context
python3 -m venv ~/.mem-context/.venv
~/.mem-context/.venv/bin/pip install mem-context
echo 'export PATH="$HOME/.mem-context/.venv/bin:$PATH"' >> ~/.zshrc
# 3. Pull embedding + translation models
ollama pull mxbai-embed-large
ollama pull qwen2.5-coder:14b
# 4. Provision
mem-context init
mem-context install claude-code
# 5. Restart AI assistant
Usage
MCP tools
| Tool | Description |
|---|
recall(query, limit?) | FTS5 + vector re-rank search |
remember(content, summary?, type?, weight?, tags?) | Store user memory |
forget(id) | Archive (weight=0) |
get(id) | Retrieve one memory |
update(id, fields) | Modify metadata |
delete_memory(id, permanent?) | Soft/hard delete |
purge_memories(scope?, type?, older_than_days?) | Bulk delete |
status(scope?) | Memory statistics |
review() | Flagged memories |
promote_all() | Export all artifacts → shared repo |
promote_memory(id) | Export one memory → shared repo |
unpromote_memory(id) | Remove from shared repo |
sync_shared_memories() | Pull from shared repo |
promote_instructions/agent/skill | Push to shared repo |
CLI
mem-context status [--scope <s>]
mem-context recall "<query>" [-n 5]
mem-context get <id>
mem-context forget <id>
mem-context delete <id> [--permanent]
mem-context purge [--type <t>] [--scope <s>]
mem-context maintain [--execute] [--dry-run]
mem-context capture transcript <path> --client claude-code
mem-context export [--scope <s>] [-o file]
mem-context import <path>
mem-context sync [memories|instructions|agents|skills|all]
mem-context promote [<id> | --all]
mem-context config show|init|edit
mem-context init [--tool <t>] [--dry-run] [--force] [--list-tools]
mem-context install <client>
Architecture
mem-context/
├── session/
│ document_store.py SQLite FTS5 — primary storage
│ chunker.py Overlapping-window chunker (for embedding)
├── retrieval/
│ engine.py RetrievalEngine — composable phases
│ phases.py DualPassQuery, SignalExtract, ExpandQuery,
│ FTSSearch, VectorReRank, ContextInject
│ embedder.py Ollama + local embedding backends
│ scoring.py Cosine similarity utility
├── capture/
│ formats.py Transcript parsers (JSONL, OpenCode, generic)
│ wrapper.py Hook entry-point
├── sync/
│ repo.py Shared git repo operations
│ exporter.py Export to YAML
│ importer.py Import from YAML
│ assembler.py Marker section merge
├── mcp/server.py FastMCP server — 15+ tools
├── config.py YAML + env config
└── provision.py AI tool detection, instruction injection
How it works
Write path
Session ends → capture hook → parse transcript → index_session()
→ SHA256 hash check → skip if unchanged
→ UPSERT into SQLite sessions table (FTS5 triggers update index)
→ _maybe_auto_export → YAML → git push
Read path
recall("jak funguje konsolidace")
→ DualPassQuery: CZ tokeny + Ollama EN překlad
→ SignalExtract: file_paths, entities, tags
→ ExpandQuery: split on _, -, CamelCase + OR
→ FTSSearch: unicode61 + BM25 ranking (limit 200)
→ VectorReRank: cosine similarity re-rank
→ ContextInject: token budget, formatting
Sync path
Startup: _full_sync() → pull → import remote → export local → push
remember(): _maybe_auto_export(id) → export one session → push
Periodic: _maybe_sync() → pull → _import_memories()
Memory types
| Type | Weight | Decay | Use |
|---|
episodic | 0.5 | 0.15/day | Auto-captured sessions |
permanent | 0.7 | 0.0 | User-saved (remember()) |
Configuration
~/.mem-context/config.yaml or .mem-context/config.yaml:
maintenance:
max_archive: 50
max_decay: 50
archive_after_days: 30
embedding:
model: auto
ollama_url: http://localhost:11434
memory:
shared:
repo: git@github.com:team/project-context.git
branch: main
mode: read-write
interval: 30
Requirements
- Python 3.11+
- Ollama:
mxbai-embed-large (1024d embedding)
- Ollama:
qwen2.5-coder:14b (CZ↔EN translate, optional)
Development
git clone ssh://git@git.montyho.com/turbyho/mem-context.git
cd mem-context
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
python3 -m pytest tests/ -q
License
MIT
mcp-name: io.github.turbyho/mem-context
mem-context — Temporal Memory MCP Server
Multi-modal RAG engine for AI assistants. Stores conversation history, conclusions,
diffs, error traces, and other development artifacts in LanceDB with vector search,
multi-factor scoring, and an LLM-driven consolidation pipeline.
Why
AI assistants lose context between sessions. mem-context persists what matters —
decisions, patterns, bugs, architecture choices — and surfaces them when relevant
via vector search. Memories decay over time unless reinforced by repeated access,
mimicking human memory.
Features
-
Vector search with dual backend — LanceDB ANN index for fast approximate
nearest-neighbor queries. Primary embedding via Ollama mxbai-embed-large
(1024d, ~670 MB). Local all-MiniLM-L6-v2 (384d) fallback when Ollama is
unavailable — no GPU or network required. Embeddings are auto-padded to
match schema dimension; switching backends is transparent.
-
Multi-factor relevance scoring — six independent factors combine into a
single 0–1 relevance score. Each factor models a different aspect:
vector_score (semantic similarity), weight_score (stored importance ×
time decay), recency_score (age in days), scope_score (project match),
access_boost (usage reinforcement), type_boost (permanent > semantic >
episodic). The model balances "what's relevant" with "what's still valid."
-
Weight decay with natural memory model — each memory type has a
configurable decay_rate: 0.15/day for episodic (session captures fade
fast), 0.03/day for semantic (extracted knowledge persists), 0 for
permanent (never decays). Decay is exponential: weight × e^(−rate × days).
Frequently accessed memories get a counteracting boost — the system
reinforces what you use, archives what you don't.
-
Deduplication by cosine similarity — new memories are compared against
existing ones before insertion. At similarity > 0.82, the new memory is
merged into the existing one (weight boost + content update) instead of
creating a duplicate. Prevents memory fragmentation from repeated captures
of the same conclusion across sessions.
-
LLM-driven consolidation pipeline — 3-phase: extract (3 days), merge
(7 days), archive (30 days). The server prepares candidates and prompts;
the host model (Claude, DeepSeek, GPT, or local Ollama) does the
reasoning. Episodic session captures → extracted conclusions (semantic) →
merged permanent knowledge → archived if unused. Runs in the background
when remember() or recall() is called — no cron needed.
-
Multi-modal storage — LanceDB columns for text content, code diffs,
file lists, error traces, tags, and metadata. Each modality is indexed
separately; vector search operates on the combined embedding. Stores not
just "what happened" but the diff and stack trace that caused it.
-
Automatic conversation capture — hooks for Claude Code (Stop event)
and manual capture for OpenCode. The wrapper binary finds the current
session's transcript, parses it into structured messages, and imports
them as episodic memories. No manual action needed — every session is
archived automatically.
-
Portable export/import — JSON export strips embeddings (re-generated on
import), keeps all metadata. Use for backup, cross-device sync, or
migrating between machines. Import deduplicates by ID — safe to run
multiple times.
-
One-command provisioning — mem-context init detects installed AI
tools (Claude Code, OpenCode, Codex, Cursor), registers the MCP server,
injects CLAUDE.md instructions, and installs slash-command skills (6 tools:
recall, remember, forget, delete, purge, status).
mem-context install adds capture hooks. Two commands, ready to use.
Installation
Linux
# 1. System dependencies
sudo pacman -S python3 python-pip # Arch / Manjaro
# nebo
sudo apt install python3 python3-pip python3-venv # Debian / Ubuntu
# nebo
sudo dnf install python3 python3-pip # Fedora
# 2. Install Ollama (for embedding)
curl -fsSL https://ollama.com/install.sh | sh
ollama serve & # Start Ollama in background
# 3. Install mem-context
python3 -m venv ~/.mem-context/.venv
~/.mem-context/.venv/bin/pip install mem-context
# 4. Add to PATH (add to ~/.bashrc or ~/.zshrc)
echo 'export PATH="$HOME/.mem-context/.venv/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# 5. Pull embedding model (~670 MB)
ollama pull mxbai-embed-large
# 6. Provision — registers MCP server + injects instructions
mem-context init # all detected AI tools
# or target a single tool:
mem-context init --tool claude-code # Claude Code only
mem-context init --tool opencode # OpenCode only
# 7. Install capture hooks (Claude Code, OpenCode)
mem-context install claude-code
mem-context install opencode # optional
mem-context install status # verify
# 8. Restart your AI assistant
macOS
# 1. System dependencies
brew install python@3.11
# 2. Install Ollama
brew install ollama
# Start Ollama: open Ollama.app or run `ollama serve &`
# 3-8. Same as Linux (steps 3-8 above)
python3 -m venv ~/.mem-context/.venv
~/.mem-context/.venv/bin/pip install mem-context
echo 'export PATH="$HOME/.mem-context/.venv/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
ollama pull mxbai-embed-large
mem-context init
mem-context install claude-code
Verify installation
# Check CLI works
mem-context status
# Check Ollama + embedding model
mem-context init --check-ollama
# List detected AI tools
mem-context init --list-tools
# Check capture hooks
mem-context install status
Manual MCP registration
If mem-context init can't register the MCP server automatically:
Claude Code:
claude mcp add --scope user mem-context ~/.mem-context/.venv/bin/mem-context-mcp
OpenCode: Add to ~/.config/opencode/opencode.json:
{
"mcp": {
"mem-context": {
"command": ["$HOME/.mem-context/.venv/bin/mem-context-mcp"],
"enabled": true,
"type": "local"
}
}
}
Updating
When a new version is released, update all components:
# 1. Upgrade the package
~/.mem-context/.venv/bin/pip install --upgrade mem-context
# 2. Update instructions, skills, and agents for all detected tools
mem-context init --force
# Target a single tool:
mem-context init --tool claude-code --instructions-only --force
mem-context init --tool opencode --instructions-only --force
# 3. Reinstall capture hooks (picks up new hook types + absolute paths)
mem-context install claude-code
mem-context install opencode
# 4. Verify everything is current
mem-context install status
mem-context init --list-tools
# 5. Restart your AI assistant
What gets updated:
| Component | Command | What |
|---|
| CLI + MCP server | pip install --upgrade | Binary, libraries, entry points |
| Instructions | mem-context init | CLAUDE.md, rules files, marked sections |
| Skills | mem-context init | Slash commands (recall, remember, forget, …) |
| Agents | mem-context init | Background agents (memory-manager) |
| Plugins | mem-context init | Client plugins (OpenCode .ts files) |
| Capture hooks | mem-context install | Hook entries in settings.json / opencode.json |
Usage
MCP tools (from AI assistant)
| Tool | Description |
|---|
remember(content, type?, weight?, tags?) | Store a memory with auto-embedding |
recall(query, scope?, token_budget?, min_score?, limit?, type_filter?) | Vector search with scoring |
forget(id) | Archive (weight=0) |
get(id) | Retrieve one memory |
update(id, fields) | Modify metadata |
delete_memory(id, permanent?) | Soft/hard delete one memory |
purge_memories(scope?, type?, older_than_days?, dry_run?) | Selective bulk delete |
status(scope?) | Memory store statistics |
review() | Flagged memories |
consolidation_candidates(scope?) | Consolidation tasks for host model |
promote_all() | Export all artifacts → shared repo |
promote_memory(id) | Export one memory → shared repo |
unpromote_memory(id) | Remove memory from shared repo |
sync_shared_memories(scope_override?) | Pull memories from shared repo |
promote_instructions() | Push CLAUDE.md → shared repo |
unpromote_instructions() | Remove CLAUDE.md from shared repo |
promote_agent(name) | Push agent → shared repo |
unpromote_agent(name) | Remove agent from shared repo |
promote_skill(name) | Push skill → shared repo |
unpromote_skill(name) | Remove skill from shared repo |
| 19 MCP tools total. | |
CLI
# Core
mem-context status [--scope <s>]
mem-context recall "<query>" [-n 5] [--scope <s>] [--min-score 0.3]
mem-context get <id>
mem-context forget <id>
mem-context delete <id> [--permanent]
mem-context purge [--type <t>] [--scope <s>] [--older-than <n>] [--dry-run]
mem-context review
# Consolidation
mem-context consolidate [--execute] [--dry-run] [--scope <s>]
# Import/Export
mem-context export [--scope <s>] [-o file]
mem-context import <path> [--scope <s>] [--re-embed]
# Capture
mem-context capture transcript <path> --client claude-code
mem-context capture pipe --client generic
# Sync (shared repo)
mem-context sync [memories|instructions|agents|skills|all]
# Promote (requires read-write)
mem-context promote [<id> | --all]
mem-context unpromote <id>
mem-context promote-instructions
mem-context unpromote-instructions
mem-context promote-agent <name>
mem-context unpromote-agent <name>
mem-context promote-skill <name>
mem-context unpromote-skill <name>
# Setup
mem-context config show|init|edit
mem-context init [--tool <t>] [--dry-run] [--force]
[--instructions-only] [--list-tools]
[--check-ollama] [--provision-ollama]
mem-context install <client>
mem-context install status
mem-context install uninstall -c <client>
How It Works
Write path: capture → store → embed
Session ends
→ capture hook fires (Claude Code: Stop)
→ transcript parsed into structured messages
→ each message stored as episodic memory
→ content embedded via Ollama (1024d) or local model (384d)
→ cosine similarity check: > 0.82 → merge, else insert
Read path: query → embed → search → score → return
recall("how do we handle auth?")
→ query embedded to 1024d vector
→ LanceDB ANN search (scope-filtered: same project + global)
→ raw candidates scored by 6-factor formula
→ sorted by final_score, filtered by min_score
→ token-budgeted: results accumulated until budget exhausted
→ returned to host model for use
Consolidation path: age → candidate → LLM → write-back
remember() or recall() called
→ check last_consolidation > interval_hours (24h)?
→ build_task: scan for episodic > 3d, semantic clusters > 7d
→ send prompts + candidates to host model
→ host model extracts conclusions → new semantic memories
→ host model merges similar semantics → permanent
→ low-weight (< 0.1) memories archived (weight = 0)
The host model does all reasoning — the server only prepares structured
prompts and candidate lists. This means consolidation quality scales with
the host model's capability (Fable 5 > Opus > Sonnet > local Ollama).
Architecture
mem-context/src/mem_context/
├── storage/lance.py LanceDB CRUD, ANN search, FTS, export/import
│ schemas.py PyArrow schemas: memories, relations, conversations
├── retrieval/embedder.py Dual-backend embedding (Ollama + local fallback)
│ scoring.py 6-factor scoring: vector × weight × decay × …
├── capture/formats.py Transcript parsers: Claude Code, OpenCode, JSON, generic
│ wrapper.py Hook entry-point: finds transcript, runs capture
│ wrapper_opencode.py OpenCode session-end wrapper
├── consolidation/
│ pipeline.py Build tasks, run extract/merge/archive phases
│ templates.py Prompt templates for each consolidation phase
│ ollama.py Local model fallback for LLM tasks
├── sync/
│ repo.py Shared git repo: clone, fetch, push
│ exporter.py Export memories → YAML files
│ importer.py Import YAML files → LanceDB
│ assembler.py Marker section merge logic
│ formats.py YAML serialization schemas
├── hooks/
│ remind_recall.py Auto-recall reminder hooks
├── mcp/server.py FastMCP server: 19 tools
├── provision.py AI tool detection, CLAUDE.md injection, skill install
├── config.py YAML + env config with auto-detection
└── scope.py Project scope resolution (config → path hash → global)
Scoring
final = vector_score × weight_score × recency_score × scope_score × access_boost × type_boost
vector_score = exp(-cosine_distance)
weight_score = sqrt(weight × e^(-decay_rate × days))
recency_score = e^(-recency_decay_rate × days)
recency_decay_rate = permanent: 0.005, semantic: 0.02, episodic: 0.05
scope_score = same_project: 1.0, global: 0.8, other: 0.4
access_boost = min(2.0, 1.0 + 0.1 × access_count)
type_boost = permanent: 2.0, semantic: 1.2, episodic: 1.0
Memory types
| Type | Default weight | Decay rate | Use |
|---|
episodic | 0.5 | 0.15/day | Session captures, debugging |
semantic | 0.7 | 0.03/day | Extracted conclusions, patterns |
permanent | 1.0 | 0.0 | Architecture decisions, conventions |
Consolidation pipeline
| Phase | Trigger | Action |
|---|
| Extract | 3 days | Episodic → host model extracts conclusions → semantic |
| Merge | 7 days | Semantic cluster by embedding → host model merges |
| Archive | 30 days | weight < 0.1 → weight = 0 |
The server prepares prompts and candidates; the host model (Claude, DeepSeek,
GPT) does the reasoning and writes results back via MCP tools.
Automatic background consolidation
No cron needed — consolidation runs automatically in the background
when remember() or recall() is called, at most once per interval_hours
(default 24h).
Configuration
All parameters are configurable via ~/.mem-context/config.yaml,
.mem-context/config.yaml, or environment variables. See
Configuration docs for all options.
# Quick overrides
export MEM_CONTEXT_CONSOLIDATION_MODEL=qwen2.5-coder:14b # model
export MEM_CONTEXT_CONSOLIDATION_TEMPERATURE=0.1 # 0.0-1.0
export MEM_CONTEXT_CONSOLIDATION_TIMEOUT=300 # seconds
| Parameter | Default | Env var | Description |
|---|
model | auto-detect | CONSOLIDATION_MODEL | 14b→7b→3b, or override |
num_ctx | 8192 | CONSOLIDATION_NUM_CTX | Context window tokens |
temperature | 0.2 | CONSOLIDATION_TEMPERATURE | Determinism (0.0–1.0) |
timeout | 120s | CONSOLIDATION_TIMEOUT | Ollama API timeout |
extract_after_days | 3 | CONSOLIDATION_EXTRACT_AFTER_DAYS | Episodic → extraction |
merge_after_days | 7 | CONSOLIDATION_MERGE_AFTER_DAYS | Semantic → merge |
archive_after_days | 30 | CONSOLIDATION_ARCHIVE_AFTER_DAYS | Low weight → archive |
max_extract | 20 | CONSOLIDATION_MAX_EXTRACT | Candidates per run |
max_merge | 10 | CONSOLIDATION_MAX_MERGE | Merge groups per run |
interval_hours | 24 | — | Hours between runs |
Model auto-detection
If no model is configured, the system:
- Detects GPU VRAM (NVIDIA, AMD, macOS Metal/Apple Silicon)
- Picks the best model that fits:
14b (9+ GB) → 7b (5+ GB) → 3b (4+ GB)
- Auto-pulls it via Ollama if not installed
- Falls back to smaller model on OOM errors
No GPU: Minimum qwen2.5-coder:3b (~4 GB system RAM, slow on CPU).
MCP path doesn't need a local model — host LLM does the work.
Scope detection
1. .mem-context/config.yaml → project_id → scope = "proj:" + hash
2. Fallback → scope = "path:" + hash(cwd)
3. `scope="global"` is explicit-only — never auto-detected
Requirements
- Python 3.11+
- Ollama (for embedding) —
mxbai-embed-large (~670 MB, recommended)
- Or:
sentence-transformers local fallback (all-MiniLM-L6-v2, 384d)
- Consolidation model: auto-detected and auto-installed (see above)
Installation options
mem-context init — instructions + skills (all 5 supported tools)
mem-context init # All detected AI tools
mem-context init --tool claude-code # Claude Code only
mem-context init --tool opencode # OpenCode only
mem-context init --tool codex # Codex only
mem-context init --tool cursor # Cursor only (project-scoped)
mem-context init --dry-run # Preview without changes
mem-context init --list-tools # Show what's detected
mem-context install — capture hooks (2 tools)
mem-context install claude-code # Stop hook → settings.local.json
mem-context install opencode # MCP server registration → opencode.json
mem-context install status # Check all
mem-context install uninstall -c claude-code # Remove
Manual MCP registration
claude mcp add --scope user mem-context ~/.mem-context/.venv/bin/mem-context-mcp
Documentation
Development
git clone ssh://git@git.montyho.com/turbyho/mem-context.git
cd mem-context
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
python3 -m pytest tests/ -q # 229 passed, 91 failed, 28 errors
License
MIT
