Multi-modal temporal memory MCP server — RAG engine over conversation history with weight-decay model and LLM-driven consolidation

These details have not been verified by PyPI

Project description

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

Document	Content
Installation	Detailed setup, Ollama, config
Configuration	Všechny parametry s vysvětlením
MCP Tools	Tool reference with schemas and examples
Architecture	Storage, scoring, retrieval pipeline
Consolidation	Pipeline phases, host model workflow
Provisioning	`mem-context init`, client support
Capture	Automatic transcript capture setup
Test Scenarios	28 sections, 100+ test cases

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

Project details

These details have not been verified by PyPI