# LoreConvo (pypi · loreconvo)

Local-first persistent session memory for Claude Code and other agents. SQLite + FTS5, no cloud.

- Trust score: 52/100 (low)
- Change this week: −16
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-10-17

## Components

- pypi · `loreconvo`: 52/100 (this document), [markdown](https://verifymcp.io/servers/labyrinth-analytics-loreconvo/loreconvo.md), [page](https://verifymcp.io/servers/labyrinth-analytics-loreconvo/loreconvo)

## Channel facts

- Registry: `pypi`
- Package: `loreconvo`
- Version: `0.10.12`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-10-17.

- **Supply Chain Security**: 32/100
  - Malware scan not yet available for this package.
  - CVE check failed: a known high-severity CVE affects mcp 1.28.1, a direct dependency. A fixed version is available.
  - Runs setuptools.build_meta at install time, a recognised build step with no custom scripting around it.
  - Dependency health was assessed across the 84 of 86 dependencies we could resolve, so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 32/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - License check failed: the license (BUSL-1.1) isn't a recognized OSI-approved license.
  - Actively maintained (last published 1 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 67/100
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 7147 tokens (~178/item across 40 items; 40 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 73/100
  - Stability observed for 22 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 71/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 0% of tool parameters carry a description.
  - Structured output schemas are declared (18% of tools); any adoption earns full credit.
- **Tool Safety**: 75/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - 0 of 1 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation; "untag_anti_pattern" implies "remove" and declares no destructiveHint at all, which the MCP spec reads as destructive by default.
  - An AI judge read all 41 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### How do I install the LoreConvo MCP server?

LoreConvo runs locally as a PyPI package, launched with uvx loreconvo. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add labyrinth-analytics-loreconvo -- uvx loreconvo
```

### Cursor

```json
{
  "mcpServers": {
    "labyrinth-analytics-loreconvo": {
      "command": "uvx",
      "args": [
        "loreconvo"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "labyrinth-analytics-loreconvo": {
      "command": "uvx",
      "args": [
        "loreconvo"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add labyrinth-analytics-loreconvo -- uvx loreconvo
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "labyrinth-analytics-loreconvo": {
      "type": "local",
      "command": [
        "uvx",
        "loreconvo"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add labyrinth-analytics-loreconvo --command uvx --arg loreconvo
```

### Hermes

```yaml
mcp_servers:
  labyrinth-analytics-loreconvo:
    command: "uvx"
    args: ["loreconvo"]
```

### Netclaw

```json
{
  "McpServers": {
    "labyrinth-analytics-loreconvo": {
      "Transport": "stdio",
      "Command": "uvx",
      "Arguments": [
        "loreconvo"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add labyrinth-analytics-loreconvo -t stdio -c uvx -a loreconvo
```

### Other

```json
{
  "mcpServers": {
    "labyrinth-analytics-loreconvo": {
      "command": "uvx",
      "args": [
        "loreconvo"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-10-16 (score 52, −5)

- [security regression] CVE-2026-59951 affects this package: high
- [security regression] Known CVEs: partial → fail

### 2026-10-15 (score 57, +1)

No change was recorded against any check on this day. Stability & Change Management went from 63 to 67. That category is still filling its 30-day observation window: 19 days of observed history at the previous scan, 20 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-13 (score 56, +11)

- [security improvement] Known CVEs: unverified → partial
- [functional improvement] Dependency health: unverified → partial

### 2026-10-12 (score 45, −23)

- [security regression] Known CVEs: partial → unverified
- [security regression] Malware scan: pass → unverified
- [functional regression] Dependency health: partial → unverified

### 2026-10-08 (score 68, +1)

No change was recorded against any check on this day. Stability & Change Management went from 33 to 43. That category is still filling its 30-day observation window: 10 days of observed history at the previous scan, 13 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-10-04 (score 67, +16)

- [security improvement] Malware scan: unverified → pass

### 2026-10-02 (score 51, +4)

- [functional improvement] Stability: unverified → 0.23

### 2026-09-29 (score 47, −15)

- [security regression] Malware scan: pass → unverified

## MCP tools (40)

### `save_session` (~577 tokens)

Save Session

Save a session summary to persistent memory.

Call this at the end of a session or when the user requests /bridge save.
Captures decisions, artifacts, skills used, and open questions for recall
in future sessions.

Args:
    title: Short descriptive title for the session
    surface: Where this session ran - 'cowork', 'code', or 'chat'
    summary: 2-3 paragraph narrative summary of what happened. Capped at
        15000 chars.
    decisions: List of key decisions made during the session. Each item
        capped at 2000 chars.
    artifacts: List of files created or modified
    open_questions: Unresolved questions to carry forward. Each item
        capped at 2000 chars.
    tags: Freeform tags for categorization
    skills_used: Skills that were invoked during this session
    project: Project name if part of a defined project
    start_date: ISO 8601 start time (defaults to now)
    end_date: ISO 8601 end time
    session_id: Optional session ID to enable deduplication with the
        auto-save hook. If a session with this ID already exists (e.g.,
        auto-saved at session end), the record is updated with the richer
        manual metadata. Artifacts from the existing record are preserved
        when the caller does not supply artifacts. If omitted, a new UUID
        is generated (existing behavior).
    external_tool_session: Set True when saving a session generated by an
        external tool (e.g., Anthropic Managed Agents). Flagged sessions are
        excluded from auto-load and search by default to prevent context
        contamination. Override exclusion with include_external=True on search,
        or set LORECONVO_EXTERNAL_TOOL_EXCLUSION=0 to disable globally.
    reasoning_notes: Optional free-form text capturing the reasoning chain
        or thought process behind decisions. Blank or None leaves the
        field empty. Capped at 15000 chars.
    summarize: If True and ANTHROPIC_API_KEY is set, send the summary to
        Claude API (Haiku) f…

Input parameters:

- `artifacts`
- `decisions`
- `end_date`
- `external_tool_session` (boolean)
- `open_questions`
- `project`
- `reasoning_notes`
- `session_id`
- `skills_used`
- `start_date`
- `summarize` (boolean)
- `summary` (string, required)
- `surface` (string, required)
- `tags`
- `title` (string, required)

### `get_recent_sessions` (~105 tokens)

Get Recent Sessions

Get recent session summaries.

Use to see what work was done recently, optionally filtered by project or skill.

Args:
    limit: Max sessions to return (default 10)
    days_back: How far back to look (default 30 days)
    project: Filter to sessions in this project
    skill: Filter to sessions that used this skill

Input parameters:

- `days_back` (integer)
- `limit` (integer)
- `project`
- `skill`

Output parameters:

- `result` (array)

### `get_session` (~38 tokens)

Get Session

Get full details of a specific session.

Args:
    session_id: The UUID of the session to retrieve

Input parameters:

- `session_id` (string, required)

### `search_sessions` (~432 tokens)

Search Sessions

Search session memory by keyword, with optional filters.

Use to find sessions where a topic was discussed, a decision was made,
or a specific skill/project was involved.

Args:
    query: Search keywords (matched against title, summary, decisions)
    persona: Filter to sessions tagged with this persona (supports prefix matching)
    tags: Filter to sessions with any of these tags
    skills: Filter to sessions that used any of these skills
    project: Filter to sessions in this project
    limit: Max results (default 10)
    include_external: If True, include sessions flagged as external_tool_session.
        Default False. Can also be enabled globally via LORECONVO_EXTERNAL_TOOL_EXCLUSION=0.
    semantic: If True, use LanceDB hybrid (vector + BM25) search instead of FTS5.
        Pro tier only. Falls back to FTS5 if index not built yet; run
        rebuild_index to build it after first Pro activation.
    include_expired: If True, include sessions whose expires_at is in the past.
        Default False (expired sessions are hidden from search).
    after: Optional ISO 8601 UTC instant (e.g. "2026-07-06T00:00:00Z"). Only
        sessions started at or after this instant are returned.
    before: Optional ISO 8601 UTC instant. Only sessions started strictly
        before this instant are returned.

        To answer a question like "what did I work on last week", resolve
        the range yourself -- you know the user's local date, the server
        does not -- and pass the two instants. Do not put date words in
        `query`; they are matched as literal keywords, not parsed.

Input parameters:

- `after`
- `before`
- `include_expired` (boolean)
- `include_external` (boolean)
- `limit` (integer)
- `persona`
- `project`
- `query` (string, required)
- `semantic` (boolean)
- `skills`
- `tags`

Output parameters:

- `result` (array)

### `get_context_for` (~158 tokens)

Get Context for Topic

Get relevant session context for a topic.

Use at the start of a session to load prior decisions and context about a topic.
Returns the most relevant session excerpts.

Args:
    topic: The topic to find context for (e.g., 'K-1 parser', 'rental insurance')
    max_results: Max excerpts to return (default 5)
    include_external: If True, include sessions flagged as external_tool_session.
        Default False.
    semantic: If True, use LanceDB hybrid search (Pro only). Falls back to FTS5
        if index not yet built.

Input parameters:

- `include_external` (boolean)
- `max_results` (integer)
- `semantic` (boolean)
- `topic` (string, required)

Output parameters:

- `result` (array)

### `configure_agent_context` (~243 tokens)

Configure Agent Context Topics

Store or update a named topic configuration for an agent.

Args:
    agent_name: Canonical agent name (^[a-z][a-z0-9-]{1,63}$).
    project: Project name matching sessions.project (^[a-z_][a-z0-9_]{0,63}$).
    topics: Non-empty list of topic strings; max 10; each max 200 chars.
        Replaces all existing topics for this (agent_name, project) pair.
    max_results_per_topic: Sessions returned per topic search. 1-10.
    enabled: Set False to disable injection without deleting the config.
    retire: Set True to soft-retire this config (status='retired').
        inject_agent_context treats a retired config like enabled=0.
        Any write with retire=False reactivates a previously retired
        config (reflected in the response's reactivated_retired_config).

Input parameters:

- `agent_name` (string, required)
- `enabled` (boolean)
- `max_results_per_topic` (integer)
- `project` (string, required)
- `retire` (boolean)
- `topics` (array, required)

### `inject_agent_context` (~159 tokens)

Inject Agent Context

Return targeted session context for an agent at session start.

If topics is provided (non-empty, len<=10), it overrides stored config.
If topics is None, stored config is used.
If topics=[], has_config reflects stored state; no injection runs.

Returns status in {"ok", "partial", "warning", "error"}.
Branch on status first; treat "warning" as skipped (not success), not
as a synonym for "ok" -- a caller that only checks `status != "error"`
will silently treat skipped or empty injection as success.

Input parameters:

- `agent_name` (string, required)
- `max_results_per_topic` (integer)
- `project` (string, required)
- `semantic` (boolean)
- `topics`

### `tag_session` (~115 tokens)

Tag Session

Tag a session with a persona for filtered recall.

Supports hierarchical personas (e.g., 'ron-bot:sql' matches 'ron-bot' queries).

Args:
    session_id: Session to tag
    persona_name: Persona identifier (e.g., 'ron-bot', 'ron-bot:sql', 'tax-prep')
    relevance_note: Optional note about why this session is relevant to the persona

Input parameters:

- `persona_name` (string, required)
- `relevance_note`
- `session_id` (string, required)

### `link_sessions` (~75 tokens)

Link Sessions

Link two related sessions.

Args:
    from_id: Source session ID
    to_id: Target session ID
    link_type: Relationship type - 'continues', 'related', or 'supersedes'

Input parameters:

- `from_id` (string, required)
- `link_type` (string)
- `to_id` (string, required)

### `get_related_sessions` (~153 tokens)

Get Related Sessions

Find sessions related to a given session by co-occurrence and embedding. Pro only.

Returns co-occurrence links (shared_term_count >= 1) and embedding-based
semantic links (shared_term_count=0 sentinel). Co-occurrence results rank
above embedding results when sorting by shared_term_count DESC.
Response version=2 signals the new format with link_type field.

Args:
    session_id: UUID of the session to find related sessions for
    limit: Max results to return (default 10, max 50)
    min_shared_terms: Minimum shared keywords required (default 3)

Input parameters:

- `limit` (integer)
- `min_shared_terms` (integer)
- `session_id` (string, required)

### `graph_session_map` (~299 tokens)

Graph Session Map

Render a Mermaid knowledge-graph neighborhood around a session or project.

Exactly one of session_id/project selects the seed. Traversal is a
bounded, read-only BFS over session_links (undirected) plus each
admitted session's attribute leaves (project/skill/persona/tag). Pro
tier adds derived (co-occurrence/embedding) and doc (LoreDocs
cross-link) edges, seed-only. Every emitted label is restricted to a
fixed character allowlist so no title/tag/skill text can alter the
diagram's structure.

Args:
    session_id: UUID of the seed session. Exactly one of session_id/project required.
    project: name of the seed project. Exactly one of session_id/project required.
    depth: number of BFS expansion hops over link edges, clamped [0, 3]
    max_nodes: node budget (sessions + attribute leaves), clamped [1, 200]

Returns a dict with version, seed, seed_found, mermaid, nodes, edges,
truncated, nodes_emitted, nodes_available, edges_emitted,
nodes_dropped_by_kind, edges_dropped_by_kind, frontier_session_ids,
edge_kinds_included, edge_kinds_omitted -- or {"error": {...}} on a
validation failure or an unavailable database.

Input parameters:

- `depth` (integer)
- `max_nodes` (integer)
- `project`
- `session_id`

### `rebuild_index` (~109 tokens)

Rebuild Semantic Index

Rebuild the LanceDB semantic search index from all stored sessions. Pro only.

Run after first Pro activation, or to recover from a corrupted index.
Downloads BAAI/bge-small-en-v1.5 (~130MB) once on first run; subsequent
runs use the cached model. May take 1-2 minutes for large session stores.

Returns a dict with 'indexed' (sessions added to index) and 'total_in_db'
(total sessions in SQLite, including those excluded from indexing).

### `get_project` (~37 tokens)

Get Project

Get project details including recent sessions and skill usage stats.

Args:
    project_name: The project identifier

Input parameters:

- `project_name` (string, required)

### `list_projects` (~16 tokens)

List Projects

List all defined projects with session counts.

Output parameters:

- `result` (array)

### `create_project` (~162 tokens)

Create Project

Create or update a project definition.

Projects group related sessions and can auto-associate based on skill usage.
All changes to project instructions are logged for audit purposes.

Args:
    name: Project identifier (e.g., 'secret-agent-man', 'project-ron')
    description: What this project is about
    expected_skills: Skills typically used in this project's sessions
    default_persona: Auto-tag new sessions with this persona
    instructions: Optional project-wide instructions or constraints
    session_id: Optional session ID for audit trail (typically provided by MCP context)

Input parameters:

- `default_persona`
- `description` (string)
- `expected_skills`
- `instructions`
- `name` (string, required)
- `session_id`

### `loreconvo_onboard` (~279 tokens)

Onboard LoreConvo

Set up or update your LoreConvo workspace configuration.

Call this once after installing LoreConvo to get a recommended setup.
Call again any time to add projects or agents, or to regenerate your
reference doc.

Creates:
\- Project registrations for each project listed
\- A config file at ~/.loreconvo/onboard_config.json
\- A reference doc (markdown) in the response -- paste it into your
  CLAUDE.md or a LoreDocs vault so your AI assistant can apply your
  conventions consistently

Args:
    name: Your workspace or team name (e.g. 'Labyrinth Analytics')
    projects: Snake_case project identifiers (e.g. ['side_hustle', 'finance'])
    agents: Agent names that will tag sessions (e.g. ['ron', 'meg'])
    tag_style: 'simple' (status + priority) or 'detailed' (adds effort,
               scout-run markers, date tag guidance)

Surfaces: code (Claude Code), cowork (Claude.ai Projects), chat (Claude.ai
chat), codex (Codex CLI). Custom values are allowed for other tools.
Agent identity: use tags=['agent:name'] -- not the surface field.

Input parameters:

- `agents`
- `name`
- `projects`
- `tag_style` (string)

### `get_skill_history` (~85 tokens)

Get Skill History

Get all sessions that used a specific skill.

Useful for understanding how often a skill is used and in what contexts.

Args:
    skill_name: The skill to look up (e.g., 'rental-property-accounting')
    days_back: How far back to search (default 90 days)

Input parameters:

- `days_back` (integer)
- `skill_name` (string, required)

Output parameters:

- `result` (array)

### `vault_suggest` (~165 tokens)

Get Context Suggestions

Get proactive context suggestions based on your session history.

Analyzes recent sessions and surfaces:
\- Sessions with unresolved open questions that need follow-up
\- Sessions with key decisions worth reviewing before starting new work
\- Skill gaps: skills expected by a project but not used recently

Use at the start of a session to find the most valuable prior context,
or when you're unsure what to work on next.

Args:
    project: Filter suggestions to this project
    persona: Filter to sessions tagged with this persona (prefix matching)
    days_back: How far back to look (default 14 days)
    limit: Max suggestions to return (default 5)

Input parameters:

- `days_back` (integer)
- `limit` (integer)
- `persona`
- `project`

### `get_tier` (~144 tokens)

Get License Tier

Return the current LoreConvo license tier and status.

Use this to confirm whether the Pro license key is loaded and valid.

Returns a dict with keys:
    is_pro      -- bool, True if Pro tier is active
    mode        -- "licensed" | "dev_bypass" | "free" | "invalid_key"
    product     -- product name from the license payload (if licensed)
    exp         -- expiry date or "never" (if licensed)
    email       -- customer email (if licensed and present)
    error       -- error message (if mode is "invalid_key")
    upgrade_url -- Stripe checkout link (present when not already Pro)

### `vault_set_tier` (~113 tokens)

Set License Tier

Activate a tier (free or pro) for LoreConvo.

Pro tier removes the free-tier session limit (default: 50 sessions).
After purchasing a Pro license, set LORECONVO_PRO=<your-license-key> in
your environment and restart the server, then call this tool with tier='pro'
to confirm Pro is active. Reverting to tier='free' re-enables limits (existing
sessions are preserved -- only new saves are blocked once the limit is hit).

Input parameters:

- `params` (required)

Output parameters:

- `result` (string)

### `export_sessions` (~220 tokens)

Export Sessions

Export portable session records to JSON or JSONL for migration.

Exports matching session fields, skills, tags, and artifacts. Links and
independent structured memory items are outside this export. Use
output_path to write to a file; omit it to receive the data inline. Use
import_sessions to load the exported file.

Args:
    output_path: File path to write export (e.g. '/tmp/loreconvo_export.json').
                 If omitted, data is returned inline.
    project: Export only sessions from this project.
    tags: Export only sessions that have any of these tags.
    days_back: Limit to sessions from the last N days. Omit for all time.
    limit: Max sessions to export (default 1000).
    format: 'json' (array wrapped in metadata) or 'jsonl' (one session per line).

Input parameters:

- `days_back`
- `format` (string)
- `limit` (integer)
- `output_path`
- `project`
- `tags`

### `export_for_anthropic` (~200 tokens)

Export Sessions for Anthropic

Export LoreConvo sessions to Anthropic managed-agents memory format. Pro only.

Produces a JSON file in 'anthropic-memory-v1' format, suitable for import into
Anthropic managed-agents memory stores. Only non-periodic, non-file-memory sessions
are exported (contamination control).

NOTE: Field mapping is preliminary pending Anthropic beta API schema stabilization.
Cassandra will signal when the schema is stable. Save the output and validate
against Anthropic docs before submitting to a managed-agents memory store.

Args:
    output_path: File path to write the export. If omitted, data is returned inline.
    project: Export only sessions from this project.
    session_ids: List of specific session UUIDs to export. Overrides project filter.
    days_back: Limit to sessions from the last N days.

Input parameters:

- `days_back`
- `output_path`
- `project`
- `session_ids`

### `import_sessions` (~152 tokens)

Import Sessions

Import sessions from a LoreConvo export file (JSON or JSONL).

Reads an export created by export_sessions and saves sessions into the
local database. Session UUIDs are preserved so re-importing is safe.

Args:
    file_path: Path to the export file (JSON or JSONL format).
    on_conflict: What to do if a session ID already exists.
                 'skip' (default) -- leave the existing session unchanged.
                 'replace' -- overwrite with the imported version.
    dry_run: If True, parse and validate the file but make no DB changes.

Input parameters:

- `dry_run` (boolean)
- `file_path` (string, required)
- `on_conflict` (string)

### `inspect_sessions` (~207 tokens)

Inspect Sessions

Inspect stored sessions: list, filter, or get full detail for one session.

Answers 'what do you know about me?' and helps users find, browse, and
understand their stored session memory.

Args:
    session_id: If provided, return full detail for this specific session.
    search: Full-text search query across title, summary, decisions, tags.
    tag: Filter by tag substring (e.g. 'agent:ron', 'side_hustle').
    surface: Filter by surface ('code', 'cowork', 'chat').
    since: Return sessions on or after this date (YYYY-MM-DD).
    limit: Max sessions to return (default 20).
    show_stats: If True, include aggregate counts (total, by_surface, by_project).

Input parameters:

- `limit` (integer)
- `search`
- `session_id`
- `show_stats` (boolean)
- `since`
- `surface`
- `tag`

### `get_stats` (~72 tokens)

Get Usage Stats

Return a usage dashboard: session counts by surface, project, and tag;
storage metrics (DB size, estimated tokens stored); and the 5 most recent sessions.

Provides visibility into your memory usage -- who saved what, how much is stored,
and what's been captured most recently. Includes hook_saves_failing status.

### `consolidate_memories` (~341 tokens)

Consolidate Memories

Run memory consolidation for a project to build a structured digest.

Analyzes recent sessions and extracts decisions, open questions, and tech
stack facts. Free tier: up to 3 consolidations per day. Pro: unlimited.

Returns a digest dict with status, decisions found, open questions, and
the formatted digest_markdown for reference.

Acquires an exclusive lock; returns status='lock_held' if another
consolidation is already running.

Args:
    project: Project name (matches the --project tag used when saving sessions)
    surface: Surface to consolidate ('code', 'cowork', 'chat', etc.) or None for all
    max_sessions: Maximum number of recent sessions to analyze (default 50)
    mode: 'heuristic' (free, default). 'llm' requires Pro (v0.6.1).
    dedup: Semantic dedup pass mode: 'off' (default), 'conservative', or
        'balanced'. When 'off' (or unset, or unrecognised), the pass does
        not run and consolidation behaves exactly as before. 'conservative'
        collapses near-verbatim restatements (cosine > 0.97); 'balanced'
        collapses paraphrases (cosine > 0.95). Can also be set via the
        LORECONVO_CONSOLIDATION_DEDUP environment variable; an explicit
        argument always overrides the env var.

Input parameters:

- `dedup`
- `max_sessions` (integer)
- `mode` (string)
- `project` (string, required)
- `surface`

### `get_memory_digest` (~166 tokens)

Get Memory Digest

Retrieve the current memory digest for a project without re-running consolidation.

Returns None if no digest exists. Use consolidate_memories first to generate one.

Optionally set disable=True to suppress auto-load injection for this digest,
or disable=False to re-enable injection. Omit disable to just read the current state.

Args:
    project: Project name
    surface: Surface filter (or None for all)
    disable: If provided, update the disabled flag on the digest
    max_tokens: Truncate digest_markdown to this estimated token limit (len // 4).
                Default 2000. If truncated, appends [TRUNCATED] marker.

Input parameters:

- `disable`
- `max_tokens` (integer)
- `project` (string, required)
- `surface`

### `set_session_expiry` (~131 tokens)

Set Session Expiry

Set or clear an expiry date on a session.

After expires_at passes, the session is excluded from search_sessions,
get_recent_sessions, and the auto-load hook. The session is NOT deleted --
recover it with search_sessions(include_expired=True).
Pass expires_at=None to clear a previously set expiry.

Args:
    session_id: ID of the session to update
    expires_at: ISO 8601 date string (e.g. '2027-01-01T00:00:00Z'), or None to clear

Input parameters:

- `expires_at` (required)
- `session_id` (string, required)

### `get_dream_log` (~129 tokens)

Get Dream Log

Return recent consolidation log entries for transparency and diagnostics.

Each entry shows: timestamp, project, surface, mode, source_count, trigger.
Use this to confirm consolidation ran, check rate limit status, and diagnose
fallbacks (e.g. api_key_found=false for LLM-mode fallback).

Args:
    project: Filter by project (or None for all projects)
    surface: Filter by surface (or None for all)
    limit: Maximum number of entries to return (default 10, newest first)

Input parameters:

- `limit` (integer)
- `project`
- `surface`

### `get_docs_for_session` (~196 tokens)

Get Docs for Session

Return LoreDocs documents cross-linked to a LoreConvo session. Pro tier only.

Queries the LoreDocs cross_product_links table. Both LoreConvo and LoreDocs
must be installed. Returns an empty list for free-tier callers (not an error).

Manual links (link_type='manual') are always sorted first. Auto-links created
with a stale embedding model are marked with is_stale=True and include an
upgrade_message.

Args:
    session_id  -- LoreConvo session UUID
    limit       -- max results (default 5)

Returns dict with:
    schema_version          -- int, for version negotiation by callers
    cross_product_available -- bool
    tier_gate               -- "satisfied" | "pro_required"
    links                   -- list of link dicts
    reason                  -- set when cross_product_available is False

Input parameters:

- `limit` (integer)
- `session_id` (string, required)

### `session_link_doc` (~197 tokens)

Link Session to Doc

Create a manual cross-product link from a LoreConvo session to a LoreDocs doc.

Manual links are accessible on all tiers. The target doc must not be in a
vault with cross_link_opt_out enabled. Both products must be installed.

Args:
    session_id  -- LoreConvo session UUID
    doc_id      -- LoreDocs document ID
    vault_id    -- LoreDocs vault containing the document

Returns dict with:
    ok      -- bool
    reason  -- failure description on error. Specific since SH-100670:
               "LoreDocs not installed" | "LoreDocs installed but
               unreachable: <detail>" | "LoreDocs schema too old: <detail>"
               | "vault not found" | "vault has cross-linking disabled"
               | "document not found"

Input parameters:

- `doc_id` (string, required)
- `session_id` (string, required)
- `vault_id` (string, required)

### `get_server_info` (~125 tokens)

Get Server Info

Return MCP compatibility status for this LoreConvo server.

Returns product version, installed mcp SDK version, tested version, and
compatibility status. Useful for diagnosing version mismatches on running
servers without requiring a restart.

Returns dict with: product_name, product_version, install_kind (wheel|editable),
version_from_source (if editable), mcp_installed, mcp_tested, mcp_accepted,
status (ok|mismatch|undetermined|disabled|internal_error), note,
error_detail (set only on internal_error), hook_saves_failing.

### `get_anti_patterns` (~157 tokens)

Get Anti-Patterns

Retrieve sessions marked as anti-patterns.

Returns a list of dicts with a 'truncated' boolean. Use at session start
or before attempting a known-tricky approach to surface past failures.

Args:
    topic: Optional keyword to filter within anti-patterns. Omit for all
           anti-patterns ordered by recency. When provided, uses FTS5 with
           a fan-out heuristic; result may be truncated if anti-patterns are
           sparse in the corpus.
    limit: Max results to return (1-100). Defaults to 10.
    project: Restrict to a specific project slug. Case-sensitive.

Input parameters:

- `limit` (integer)
- `project`
- `topic`

Output parameters:

- `result` (array)

### `tag_as_anti_pattern` (~101 tokens)

Tag Session as Anti-Pattern

Mark an existing session as an anti-pattern. Idempotent.

Args:
    session_id: The sessions.id value to mark (TEXT <= 255 chars).
    source: Attribution for this tag (e.g., 'claude-code', 'agent:gina').
    reason: Human-readable reason for the tag. Stored in audit log.

Input parameters:

- `reason` (string)
- `session_id` (string, required)
- `source` (string)

### `untag_anti_pattern` (~128 tokens)

Untag Anti-Pattern

Remove an anti-pattern tag from a session. Idempotent.

The audit log row is written on successful removal; not written if the
session was not tagged (idempotent no-op case).

Args:
    session_id: The sessions.id value to untag (TEXT <= 255 chars).
    source: Attribution for this untag (e.g., 'claude-code', 'admin').
    reason: Human-readable reason for the removal. Stored in audit log.

Input parameters:

- `reason` (string)
- `session_id` (string, required)
- `source` (string)

### `pin_session` (~187 tokens)

Pin Session

Pin or unpin a session to exclude it from automated cleanup.

keep_forever=True (default): session excluded from future cleanup;
  any existing expires_at is cleared atomically.
keep_forever=False: pin removed; session can receive expiry again.

Returns:
    {"ok": True, "session_id": "...", "keep_forever": bool}
    {"ok": False, "code": "invalid_session_id", "message": "..."}
    {"ok": False, "code": "invalid_param", "message": "..."}
    {"ok": False, "code": "session_not_found", "message": "..."}
    {"ok": False, "code": "db_error", "message": "..."}
    {"ok": False, "code": "feature_disabled", "message": "..."}

Input parameters:

- `keep_forever`
- `session_id` (string, required)

### `save_memory_item` (~310 tokens)

Save Memory Item

Save a structured memory item: a decision, open question, or artifact.

Replaces the old free-text decisions/open_questions/artifacts lists on
sessions with queryable, lifecycle-tracked rows. Idempotent when
external_id is given: a second save with the same (project, external_id)
returns the existing item (created=False) instead of creating a duplicate.

Args:
    item_type: One of 'decision', 'open_question', 'artifact'.
    title: The decision text, the question text, or the artifact identifier.
        Capped at 4096 chars.
    body: Free-text detail/rationale for decision/open_question. Ignored
        for artifacts -- use artifact_type instead. Capped at 4096 chars.
    session_id: Originating session, if any. Must reference an existing session.
    project: Project namespace (default 'unspecified').
    tags: Freeform tag list.
    metadata: Freeform key-value metadata (mainly for artifacts).
    external_id: Caller-supplied dedup key, unique per (project, external_id).
    artifact_type: For item_type='artifact', the artifact's type (e.g. 'file', 'url').

Input parameters:

- `artifact_type`
- `body`
- `external_id`
- `item_type` (string, required)
- `metadata`
- `project` (string)
- `session_id`
- `tags`
- `title` (string, required)

### `query_memory_items` (~157 tokens)

Query Memory Items

Query structured memory items by type, project, status, and recency.

Args:
    item_type: Filter to 'decision', 'open_question', or 'artifact'.
    project: Filter to a project namespace.
    status: Filter to a lifecycle status (e.g. 'active', 'open', 'retired').
    artifact_type: Filter artifacts by their artifact_type. Only applies
        with item_type='artifact'.
    days: Only items created in the last N days.
    limit: Max rows to return (default 50, max 200).

Input parameters:

- `artifact_type`
- `days`
- `item_type`
- `limit` (integer)
- `project`
- `status`

### `transition_memory_item` (~152 tokens)

Transition Memory Item

Move a memory item through its lifecycle.

Valid transitions: 'retire' (decision -> retired); 'answer' and
'wont-answer' (open_question -> answered / wont-answer). Already-closed
items return code='already_closed' so callers can retry idempotently.

Args:
    item_id: The memory item's id.
    transition: 'retire', 'answer', or 'wont-answer'.
    reason: Optional free-text reason recorded on close.
    closing_session_id: Session performing the transition, if any. Must
        reference an existing session.

Input parameters:

- `closing_session_id`
- `item_id` (string, required)
- `reason`
- `transition` (string, required)

### `update_memory_item` (~215 tokens)

Update Memory Item

Correct a memory item's title, body, tags, or metadata, or move it between projects.

Moving projects requires allow_project_change=True as an explicit guard
against accidental cross-project moves. If the item has an external_id,
the move is rejected with code='external_id_conflict' when the
destination project already has an item with that external_id.

Args:
    item_id: The memory item's id.
    title: New title, if changing.
    body: New body, if changing. Capped at 4096 chars.
    tags: New tag list, if changing (replaces, not merges).
    metadata: New metadata dict, if changing (replaces, not merges).
    new_project: Destination project, if moving.
    allow_project_change: Must be True to actually move projects.

Input parameters:

- `allow_project_change` (boolean)
- `body`
- `item_id` (string, required)
- `metadata`
- `new_project`
- `tags`
- `title`

## Diagnostics

Captured diagnostic sections: Provenance, Install scripts, Vulnerabilities, Dependencies. The full working is on the page: https://verifymcp.io/servers/labyrinth-analytics-loreconvo/loreconvo#diagnostics

## Score history

- 2026-10-17: 52
- 2026-10-16: 52
- 2026-10-15: 57
- 2026-10-14: 56
- 2026-10-13: 56
- 2026-10-12: 45
- 2026-10-08: 68
- 2026-10-05: 67
- 2026-10-04: 67
- 2026-10-03: 51
- 2026-10-02: 51
- 2026-10-01: 47
- 2026-09-30: 47
- 2026-09-29: 47
- 2026-09-28: 62
- 2026-09-27: 47
- 2026-09-26: 47
- 2026-09-25: 47

## Common questions

### What is the LoreConvo MCP server?

LoreConvo is an MCP server listed in the public MCP registry as io.github.labyrinth-analytics/loreconvo. Local-first persistent session memory for Claude Code and other agents. SQLite + FTS5, no cloud. This page covers its PyPI package (loreconvo).

### Is the LoreConvo MCP server safe to use?

LoreConvo scores 52 out of 100 on VerifyMCP. We recorded 1 known advisory against it as of 17 October 2026. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the LoreConvo MCP server expose?

LoreConvo exposes 40 tools: save_session, get_recent_sessions, get_session, search_sessions, get_context_for, and 35 more. Their descriptions and schemas cost roughly 7,007 tokens of context every time the server is loaded.

### Is the LoreConvo MCP server still maintained?

LoreConvo is still listed as active in the MCP registry. We last reached this channel on 17 October 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the LoreConvo MCP server under?

LoreConvo declares the BUSL-1.1 licence, which is not on the OSI-approved list. Read the terms before using it at work, and note this covers the source only, not the cost of any service it calls.

## Links

- PyPI project: https://pypi.org/project/loreconvo/
- Socket report: https://socket.dev/pypi/package/loreconvo
- Repository: https://github.com/labyrinth-analytics/loreconvo
- Changelog RSS feed: https://verifymcp.io/servers/labyrinth-analytics-loreconvo/loreconvo.xml
- Changelog JSON feed: https://verifymcp.io/servers/labyrinth-analytics-loreconvo/loreconvo.json
- HTML version of this page: https://verifymcp.io/servers/labyrinth-analytics-loreconvo/loreconvo