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. Reasoning continuity captures tried/rejected approaches and recalls dead ends at the start of each new session, so the same failed path is never explored twice.

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 localhost-only HTTP server (token-authenticated) 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, lemma_memory_add) → Pattern (type: "pattern") → Guide (how you work, lemma_guide_distill → lemma_guide_practice)

No project-file modification: Lemma injects memory through the MCP prompt layer — the system prompt and tool descriptions — and never writes to AGENTS.md or any project file. This works identically on every MCP client. (Legacy <!-- lemma:* --> blocks left by older versions are auto-cleaned on startup.)

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

Memory (10)

Tool	Purpose
lemma_memory_read	Read/search fragments. Summary mode or full detail by ID
lemma_memory_add	Save findings. Auto-redacts secrets, detects duplicates and conflicts
lemma_memory_update	Update fragment by ID
lemma_memory_feedback	Positive/negative feedback, adjusts confidence
lemma_memory_forget	Delete fragment
lemma_memory_merge	Merge fragments, inherit relations & guide links
lemma_memory_relate	Create typed links (contradicts, supersedes, supports, related_to)
lemma_memory_stats	Fragment counts, confidence, project breakdown
lemma_memory_audit	Integrity check for orphans, duplicates, anomalies
lemma_memory_library	Full knowledge base snapshot with analysis signals and suggestions

Guides (7)

Tool	Purpose
lemma_guide_get	Get guides sorted by usage, filter by category or task
lemma_guide_practice	Record guide usage. Auto-creates guide if missing
lemma_guide_create	Create guide with detailed manual
lemma_guide_distill	Transform memory → guide learning (bidirectional link)
lemma_guide_update	Update guide properties, anti-patterns, pitfalls
lemma_guide_forget	Remove guide
lemma_guide_merge	Merge guides, inherit source memories

Sessions (5)

Tool	Purpose
lemma_session_start	Start traced session, pre-loads relevant context
lemma_session_attempt	Record a tried approach (rejected/partial/promising) — dead ends are valuable memory
lemma_session_end	End session with review, auto-linking, and suggestions
lemma_session_stats	Virtual session statistics
lemma_suggestion_respond	Accept or dismiss a surfaced improvement suggestion (teaches Lemma your preferences)

Intelligence (4)

Tool	Purpose
lemma_conflict_scan	Scan all memories for contradictions
lemma_proactive_analysis	Full knowledge base analysis: stale, orphan, distill, deprecated
lemma_project_analytics	Cross-session project health, growth rate, skill coverage
lemma_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

Lemma is local-first by design:

• Local storage — all data stays in ~/.lemma/; nothing is sent to external servers.
• Secret redaction — secrets are scrubbed from memory fragments AND from traffic logs (17 regex patterns for API keys, tokens, connection strings; position-based so over-redaction and overlap bugs are avoided).
• Visualizer hardening — the visualizer binds 127.0.0.1 only (never 0.0.0.0), requires an X-Lemma-Token, and uses a narrow localhost CORS allow-list (no Access-Control-Allow-Origin: *).

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