LoreConvo

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. Pro tier also includes ``semantic_index`` with session counts for the LanceDB semantic search index. 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…

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…

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 identifie…

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_di…

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. Starts the rebuild in a background thread and returns immediately with a status handle. The server remains responsive to other calls while the rebuild runs. Call rebuild_index_status() to track progress. The first run downloads BAAI/bge-small-en-v1.5 (~130MB; cached afterwards). Expect roughly 3-10 minutes per thousand sessions depending on hardware. A rebuild already in progress returns status 'busy' with the current progress percentage. Returns: - {'status': 'started', 'message': '...'} when a new rebuild …

Return the current status of a background semantic-index rebuild. Call after rebuild_index() to monitor progress. Returns 'idle' when no rebuild has been started or the last rebuild has finished. Returns: - {'status': 'idle', 'message': '...'} - {'status': 'running', 'phase': '...', 'progress': N, 'total': N, 'progress_pct': N, 'elapsed_s': N.N} - {'status': 'complete', 'message': '...', 'indexed': N, 'total_in_db': N, 'exclusions': {reason: count}, 'elapsed_s': N.N} - {'status': 'error', 'message': '...'}

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. Ig…

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_question…

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). Short alphabetic tokens (<=10 chars) are prefix-matched automatically. Append `*` to force prefix matching on longer terms (e.g., "consolid*"). 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 …

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 …

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 (replac…

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. When `project` is given and the initial window returns no suggestions but the project still has sessions, the window is expanded progressively (30, 90, 365, then all-time days) so …