Skip to main content
Glama

npm version npm downloads License: MIT Node CI

Listed on mcpservers.org Glama score mcprush Audited by AddonAudit

th-memory-mcp

Local-first memory for AI coding agents, over MCP. One SQLite file remembers your preferences, lessons, decisions and project context, then hands the right slice back to the agent before each task. Hybrid FTS5 + local vectors, Thai/English aware, no cloud, no API keys.

What you get

๐Ÿง  16 MCP tools

remember, recall, get_context, get_profile, save_lesson, consolidate, link_memory, merge_memory, update_memory, forget, search_history, get_recent_interactions, memory_stats, export_memory, import_memory, extract_memories

๐Ÿ”Ž Hybrid retrieval

FTS5 (Thai word-segmented, tone-tolerant) fused with 512-dim local vectors via RRF, then rescored by confidence, importance, recency and scope

๐Ÿ•ฐ Temporal + conflict-aware

validity windows, supersession chains, duplicate/contradiction classification; ambiguous evidence is preserved, never silently destroyed

๐Ÿ”Œ Works with your harness

OpenCode plugin with background capture; Claude Code hooks; Codex, Cursor, Qwen Code, DeepSeek Harness via MCP

๐Ÿ” Opt-in security

RBAC over every tool, identity-derived scope isolation with grants, a content-free audit_log, whole-DB SQLCipher encryption with rotation/backups/drills, and per-user capture attribution

๐Ÿ“ด Offline by default

no network calls, no accounts, no API keys โ€” the database is a single local file

Related MCP server: MCP Vector Memory

Performance

Measured with the internal harness on one machine, seed 42; profile normal = 20,000 memories / 5,000 queries. Each cell shows the latest three runs, oldest โ†’ newest.

metric

2.5.1

3.0.0

3.0.1

insert throughput (mem/s)

352.6 / 331.9 / 320.5

331.7 / 277.4 / 361.5

348.0 / 337.4 / 352.9

retrieve @20k (ms)

103.9 / 106.2 / 90.3

75.8 / 87.2 / 82.2

76.7 / 74.4 / 73.5

get_context @20k (ms)

102.5 / 116.5 / 86.2

70.3 / 70.7 / 80.5

70.5 / 68.5 / 69.5

recall p95 (ms)

1.00 / 2.00 / 1.00

1.00 / 2.00 / 1.00

2.00 / 2.00 / 1.00

DB size (MB)

101.1 / 101.1 / 101.1

101.1 / 101.3 / 100.7

100.7 / 100.7 / 100.7

Observation: v3.0.x retrieve / get_context took ~68โ€“87 ms vs ~86โ€“116 ms for 2.5.1; peak RSS was higher (quick ~262โ€“306 MB vs ~110โ€“199 MB; normal ~432 MB vs ~113โ€“203 MB). The auth/encryption modules and native better-sqlite3-multiple-ciphers coincide with the increase, but these runs do not isolate which component consumed the extra memory.

Full performance history, three-run tables, and quality gates โ†’ docs/PERFORMANCE.md

Install in 60 seconds

git clone https://github.com/worakorn-prince/th-memory-mcp.git
cd th-memory-mcp && npm install && npm run build

# one DB shared by the server and the plugin
setx MEMORY_DB_PATH "%CD%\data\memory.db"          # Windows
# export MEMORY_DB_PATH="$PWD/data/memory.db"      # macOS/Linux (add to your shell profile)

Then register the MCP server with the ready-made block in setup/opencode.example.json (or run npm run quickstart). Optional agent rules: setup/AGENTS.memory.example.md.

Documentation

Topic

Where

Full documentation โ€” requirements, architecture, every tool, the CLI, daily usage

docs/Docs.md

Full documentation (เน„เธ—เธข)

docs/Docs.th.md

Authentication, RBAC and scope isolation

docs/Docs.md ยง Authentication

Encryption at rest, key rotation, backup / verify / restore / drill

docs/Docs.md ยง Encryption

Threat model and residual risks

SECURITY.md

Upgrade from 2.x

MIGRATION_v3.md

Performance measurements

docs/PERFORMANCE.md

Thai search internals (reusable module)

docs/thai-fts.md

Changelog

CHANGELOG.md

Harness setup

Harness

Guide

OpenCode

setup/opencode.example.json + npm run quickstart

Claude Code

setup/CLAUDE_CODE_HOOKS.md

Codex

setup/CODEX_SETUP.md

Cursor

setup/CURSOR_SETUP.md

Qwen Code

setup/QWEN_SETUP.md

DeepSeek Harness

setup/DSH_SETUP.md

Security in one paragraph

With no environment variables set, the server behaves exactly like 2.5.x: no auth, plaintext database, no extra I/O. Security is opt-in and independent: MEMORY_AUTH=on adds a verified identity, a single role gate over all 16 tools, identity-derived scope isolation with explicit grants, and an audit_log; MEMORY_ENCRYPTION=on encrypts the whole database (SQLCipher via better-sqlite3-multiple-ciphers) and adds db rekey, db verify-backup, db restore and db drill. Details, threat model and residual risks: SECURITY.md.

License

MIT ยฉ 2026 worakorn-prince

Available Tools

16 tools
consolidateConsolidate memoriesA

Cluster similar memories via embedding similarity and optionally create derived/consolidated memories linked via 'derived_from'. Use during periodic consolidation.

Inputs: derive, userId, projectId, sessionId, +2 more.

export_memoryExport memory to JSONA

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.

Inputs: filename, includeInteractions.

extract_memoriesExtract memories from interactionsA

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).

Inputs: kind, apply, limit, userId, +1 more.

forgetForget a memory entryA

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).

Inputs: target_id (required), type.

get_contextGet assembled contextB

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.

Inputs: limit, query, userId, maxTokens, +4 more.

get_profileGet user profileA

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.

Inputs: userId, projectId, sessionId.

get_recent_interactionsRecent interactionsA

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.

Inputs: kind, limit, sessionId.

import_memoryImport memoriesA

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.

Inputs: file, json, apply, userId, +1 more.

memory_statsMemory statisticsA

Summarize memory usage: interaction counts by kind, preference/lesson totals, DB file size, oldest/newest interaction timestamps, and profile sections.

Inputs: no named parameters.

merge_memoryMerge memoriesA

Merge a duplicate/near-duplicate memory into a canonical one. The source becomes superseded and provenance is recorded in metadata.merged_from.

Inputs: sourceId (required), targetId (required).

recallRecall memoryA

Search preferences + lessons via full-text index, plus recent matching interactions. Use before starting a new task.

Inputs: topic (required), limit.

rememberRemember preferenceA

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().

Inputs: key (required), value (required), category (required).

save_lessonSave lessonA

Record a lesson learned from a correction: what situation, what mistake, what is the correct way. Call immediately after the user corrects your work.

Inputs: mistake (required), situation (required), correction (required).

search_historySearch prompt historyA

Search past user prompts (kind='prompt') by keyword. Returns timestamped snippets truncated to 200 chars each.

Inputs: query (required), limit, sessionId.

update_memoryUpdate a memoryA

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).

Inputs: id (required), content, summary, metadata, +5 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    A3.7/5.0

    Scored across 16 tools

    Disambiguation4/5

    Most tools target distinct actions and memory types, but retrieval is split across recall, get_context, get_profile, and search_history, and remember vs update_memory has some conceptual overlap. The descriptions clarify these boundaries, but an agent may still hesitate over which retrieval tool to use first.

    Naming Consistency4/5

    Most names follow a clear snake_case verb_noun pattern such as save_lesson, get_profile, link_memory, and update_memory. A few exceptions like remember, recall, forget, consolidate, and memory_stats deviate from that pattern but remain readable and predictable enough.

    Tool Count4/5

    At 16 tools the set is slightly on the heavy side, but each tool covers a meaningful part of a sophisticated memory lifecycle: capture, retrieval, curation, graph operations, import/export, and stats. It does not feel padded, though a smaller surface could reduce cognitive load.

    Completeness5/5

    The tool surface covers the full memory lifecycle: creation via remember/save_lesson/extract/import, retrieval via recall/get_context/profile/history, updates, deletion, linking, merging, consolidation, export, and stats. No obvious CRUD or lifecycle gap remains for the stated memory-management purpose.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Provides persistent local memory functionality for AI assistants, enabling them to store, retrieve, and search contextual information across conversations with SQLite-based full-text search. All data stays private on your machine while dramatically improving context retention and personalized assistance.
      3
      -
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Provides AI coding agents with persistent, long-term memory through local semantic search and SQLite storage. It enables agents to save and retrieve architectural decisions or project context across different conversation sessions without requiring cloud services.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides persistent cross-session memory and full-text search for AI coding assistants, storing project context, decisions, and preferences while enabling searchable access to conversation history via local SQLite.
      8
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Provides AI coding assistants with persistent memory storage using a local SQLite database. Enables tools to remember project details, notes, and relationships across sessions to maintain context and reduce repetitive explanations.
      17
      4
      MIT