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.

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

Outputs a full analysis of all memories, guides, relations, stale fragments, distill candidates, and suggested actions. Useful for periodic maintenance and review.

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