# th-memory-mcp [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/worakorn-prince/th-memory-mcp  
**GitHub Stars:** 3  
**npm Downloads (last month):** 1809  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/th-memory-mcp

## Description
Adaptive Memory MCP server - SQLite-backed memory for OpenCode

## Tools
Capabilities this server exposes over MCP:

- **remember** — Save or update a user preference (category+key upsert). Re-saving the same key increases confidence by 0.1 (cap 1.0). Returns the row id for forget().
- **recall** — Search preferences + lessons via full-text index, plus recent matching interactions. Use before starting a new task.
- **get_profile** — Get the distilled user profile: profile sections, top preferences by confidence (max 15), and the 5 most recent lessons. Optional userId/sessionId/projectId scope the auto-projected memories; without them only GLOBAL memories are included.
- **save_lesson** — Record a lesson learned from a correction: what situation, what mistake, what is the correct way. Call immediately after the user corrects your work.
- **search_history** — Search past user prompts (kind='prompt') by keyword. Returns timestamped snippets truncated to 200 chars each.
- **forget** — Delete one memory row (preference, lesson or interaction) by id and sync the search index. Pass type when you know it (ids from remember are preference ids, from save_lesson are lesson ids).
- **memory_stats** — Summarize memory usage: interaction counts by kind, preference/lesson totals, DB file size, oldest/newest interaction timestamps, and profile sections.
- **get_recent_interactions** — List recently captured raw interactions (newest first) as [id] ts [kind] content lines. Optionally filter by kind. Use for auditing history or before distilling memory.
- **export_memory** — Export preferences, lessons, profile (and optionally raw interactions) to a JSON file under data/exports/. Only writes inside that directory. Returns the file path, size in bytes and a JSON preview.
- **get_context** — Assemble relevant memories for the current task via hybrid retrieval (+ optional memory-graph expansion), with token budgeting. Use to load memory into context before a task.
- **consolidate** — Cluster similar memories via embedding similarity and optionally create derived/consolidated memories linked via 'derived_from'. Use during periodic consolidation.
- **link_memory** — Create a typed relationship between two memories in the graph (supports/contradicts/supersedes/derived_from/related_to/caused_by/depends_on).
- **merge_memory** — Merge a duplicate/near-duplicate memory into a canonical one. The source becomes superseded and provenance is recorded in metadata.merged_from.
- **update_memory** — Update mutable fields (summary/importance/confidence/valid_from/valid_until/metadata) in place. If content changes, a superseding memory is created by default (set supersede=false to edit in place).
- **import_memory** — Import memories from a JSON array or a .json file inside data/exports/. Validates type, dedupes against existing memories, and never overwrites active memory blindly. Dry-run by default; pass apply=true to insert.
- **extract_memories** — Scan recent captured interactions for memory-intent phrases and propose memory candidates (deterministic, no LLM). Dry-run by default; pass apply=true to create them (source=captured).

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "th-memory-mcp": {
    "command": "npx",
    "args": ["-y","th-memory-mcp"],
    "env": {
      "MEMORY_DB_PATH": ""
    }
  }
}
```

**Requires environment variables:** `MEMORY_DB_PATH` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What th-memory-mcp does

th-memory-mcp gives MCP-compatible agents persistent memory backed by a local SQLite file. It focuses on user preferences, lessons learned from corrections, captured prompts and interactions, and a distilled profile. Memory records can carry confidence, importance, validity periods, lifecycle states, and relationships such as supersedes, contradicts, supports, or derived_from.

The server is designed for OpenCode, where its companion `learning-capture` plugin can record prompts, tool activity, errors, and compaction events. The MCP tools can also be used from other clients, including Claude Code, Qwen Code, Codex, and Cursor. Data remains on the local machine, and secrets matching patterns such as API keys, passwords, and tokens are filtered before capture.

## How it works

The server runs as a Node.js stdio process and reads and writes a shared SQLite database. `remember` upserts a preference by category and key; saving the same key again raises confidence by 0.1, up to 1.0. `save_lesson` stores a situation, mistake, and correction, while `recall`, `get_profile`, and `search_history` retrieve stored knowledge and prior prompts.

For task preparation, `get_context` combines full-text keyword search with dependency-free lexical fuzzy matching and can expand results through the memory graph. It applies a token budget when assembling the returned context. `consolidate` clusters similar memories and can create derived records with provenance links. `link_memory`, `merge_memory`, and `update_memory` support relationship, duplicate, and field management while preserving supersession behavior for content changes.

Captured interactions can be reviewed with `get_recent_interactions`, summarized with `memory_stats`, or processed by `extract_memories`, which proposes candidates from memory-intent phrases without using an LLM. Import and export operate through JSON files under `data/exports/`.

## Setup and configuration

Use Node.js 22, 24, or 26 patched releases and npm. The project can be built from source with `npm install` followed by `npm run build`, then started with `npm start`. It can also be installed globally from npm or run with `npx th-memory-mcp`.

Set `MEMORY_DB_PATH` to the SQLite file that both the MCP server and any capture plugin should use. On Windows, configure it with `setx`; on macOS or Linux, export it from the shell profile. OpenCode configuration points its local MCP command at `dist/index.js` or the installed `th-memory-mcp` executable.

The optional OpenCode plugin is deployed as `~/.config/opencode/plugins/learning-capture/index.ts` and supports OpenCode V1 and V2 layouts. Restart OpenCode after changing its configuration. The server itself needs no external service, account, or API key.

## Tools and capabilities

- Store and update preferences with confidence scoring through `remember`.
- Search preferences, lessons, and matching recent interactions with `recall`.
- Retrieve profile sections, high-confidence preferences, and recent lessons with `get_profile`.
- Record corrections as structured lessons with `save_lesson`.
- Search timestamped prompt snippets with `search_history`.
- Assemble token-budgeted task context with hybrid retrieval through `get_context`.
- Create, merge, update, consolidate, and relate memory records.
- Import validated JSON memories in dry-run or apply mode, and export data with a preview.
- Inspect recent interactions and database usage statistics.
- Extract candidate memories deterministically from captured interactions.

_Full upstream README: https://allmcps.com/mcp/th-memory-mcp/readme_