LoreConvo

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

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.

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)

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.

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

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.

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.

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

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)

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.

Get project details including recent sessions and skill usage stats. Args: project_name: The project identifier

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

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)

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 full details of a specific session. Args: session_id: The UUID of the session to retrieve

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)

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.

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)

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.

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.

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.

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

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

List all defined projects with session counts.

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.

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": "..."}

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

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

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

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…

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.

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"

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

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.

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

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.

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.

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.

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

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)