Lemma — Persistent Memory for LLMs via MCP

English | Türkçe

Lemma is an MCP server that gives LLMs persistent, cross-session memory. Memories are injected automatically into every session — no explicit tool call needed. Knowledge evolves through use: frequently accessed memories strengthen, unused ones fade, and patterns are promoted into reusable skills. An autonomous intelligence layer runs in the background — detecting conflicts, suggesting actions, and auto-linking related knowledge.

Memory Visualizer — lemma -vis

Quick Start

Add Lemma to your MCP client configuration:

Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json Claude Code (Linux): ~/.claude.json or ~/.claude/settings.json opencode: ~/.config/opencode/opencode.json (Linux/macOS) or %APPDATA%\opencode\opencode.json (Windows)

{
  "mcpServers": {
    "lemma": {
      "command": "npx",
      "args": ["-y", "lemma-mcp@latest"]
    }
  }
}

Using @latest ensures npx always fetches the newest version.

Requirements: Node.js 20.0.0 or higher

CLI Usage

lemma -lib    # Library Mode: snapshot of your entire knowledge base
lemma -vis    # Visualizer: interactive memory graph in browser
lemma -vis -p 8080  # Visualizer on custom port (default: 3456)

Library Mode (-lib) outputs a full analysis of all memories, guides, relations, stale fragments, distill candidates, and suggested actions. Useful for periodic maintenance and review.

Visualizer (-vis) starts a local HTTP server and opens an interactive D3.js force-directed graph of your memory fragments in the browser. Nodes represent memories (sized by confidence + access count, colored by type). Links show relations and associations. All changes (edit, delete, link, unlink) write directly to the SQLite database in real-time. Cross-platform: works on macOS, Linux, and Windows.

How It Works

Memories are injected into tool descriptions via tools/list. The LLM starts every session already knowing its most important memories — works on every MCP client.

3-layer injection:

• Full content for top memories (token-budgeted)
• Summary index for remaining memories
• Active guides with learnings

Memory types: fact, pattern, lesson, warning, context

Knowledge pipeline: Memory (what you know, memory_add) → Pattern (type: "pattern") → Guide (how you work, guide_distill → guide_practice)

AGENTS.md injection: Lemma automatically injects a system prompt into your project's AGENTS.md, teaching the LLM how to use the memory system effectively. This ensures consistent behavior across all MCP clients.

Autonomous Intelligence

Lemma runs intelligence in the background — no manual triggering needed:

• Conflict Detection: Automatically checks new memories against existing knowledge for contradictions. Reports conflicts with suggestions to resolve.
• Proactive Suggestions: After adding memories or practicing guides, suggests actions like distilling patterns, merging duplicates, or refining low-performing guides.
• Auto-linking: Frequently co-read memories and topic-overlapping fragments are automatically connected with relations.

Manual deep analysis is also available via dedicated tools.

Tools (24)

Memory (11)

Tool	Purpose
memory_read	Read/search fragments. Summary mode or full detail by ID
memory_add	Save findings. Auto-redacts secrets, detects duplicates and conflicts
memory_update	Update fragment by ID
memory_feedback	Positive/negative feedback, adjusts confidence
memory_forget	Delete fragment
memory_merge	Merge fragments, inherit relations & guide links
memory_relate	Create typed links (contradicts, supersedes, supports, related_to)
memory_stats	Fragment counts, confidence, project breakdown
memory_audit	Integrity check for orphans, duplicates, anomalies
memory_library	Full knowledge base snapshot with analysis signals and suggestions

Guides (8)

Tool	Purpose
guide_get	Get guides sorted by usage, filter by category or task
guide_practice	Record guide usage. Auto-creates guide if missing
guide_create	Create guide with detailed manual
guide_distill	Transform memory → guide learning (bidirectional link)
guide_update	Update guide properties, anti-patterns, pitfalls
guide_forget	Remove guide
guide_merge	Merge guides, inherit source memories

Sessions (3)

Tool	Purpose
session_start	Start traced session, pre-loads relevant context
session_end	End session with review, auto-linking, and suggestions
session_stats	Virtual session statistics

Intelligence (4)

Tool	Purpose
conflict_scan	Scan all memories for contradictions
proactive_analysis	Full knowledge base analysis: stale, orphan, distill, deprecated
project_analytics	Cross-session project health, growth rate, skill coverage
semantic_search	TF-IDF similarity search across memories

Configuration

Optional config at ~/.lemma/config.json:

{
  "token_budget": {
    "full_content": 5000,
    "summary_index": 1000,
    "guides_detail": 1000
  },
  "injection": {
    "max_full_content_fragments": 15,
    "max_summary_fragments": 30,
    "max_guides": 20
  },
  "virtual_session": {
    "timeout_minutes": 30
  }
}

File Locations

OS	Path
Windows	C:\Users\{username}\.lemma\
macOS/Linux	~/.lemma/

Files: lemma.db (SQLite), config.json, sessions/, logs/

Search

Lemma uses SQLite FTS5 full-text search for memory lookup, dedup, and topic overlap detection.

Architecture:

• searchAndSortFragments() — FTS5 full-text search, fallback to in-memory ranking
• findSimilarFragment() — FTS5 BM25-based dedup with keyword overlap fallback
• findTopicOverlaps() — FTS5 search + word overlap scoring for related fragment detection

Data Storage

All data is stored in a single SQLite database (~/.lemma/lemma.db):

Table	Purpose
memories	Memory fragments (FTS5 + metadata)
guides	Procedural knowledge with learnings
sessions	Session tracking and outcomes
relations	Typed links between memories
guide_learnings	Per-guide accumulated learnings
guide_memory_links	Bidirectional guide ↔ memory links

Legacy JSONL files are automatically migrated on first run.

Security

All data is stored locally in ~/.lemma/. Nothing is sent to external servers. Secrets are automatically redacted from memory fragments (17 regex patterns for API keys, tokens, connection strings).

Documentation

• Development Guide — Architecture, project structure, testing
• Handlers Refactor — Targeted SQL migration plan
• Roadmap — v0.9, v0.10, v1.0 plans
• Research — Academic papers that influenced Lemma's design
• Changelog — Version history

License

MIT