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 decisions: List of key decisions made during the session artifacts: List of files created or modified open_questions: Unresolved questions to carry forward 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. Stored as-is; blank or None leaves the field empty. summarize: If True and ANTHROPIC_API_KEY is set, send the summary to Claude API (Haiku) for compression before saving. Opt-in only; defaults to False. Falls back to the raw summary on any API error or if the key is absent. See INSTALL.md Privacy Note.

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

Get full details of a specific session.

Args: session_id: The UUID of the session to retrieve

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

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.

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

Link two related sessions.

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

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)

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 details including recent sessions and skill usage stats.

Args: project_name: The project identifier

List all defined projects with session counts.

Create or update a project definition.

Projects group related sessions and can auto-associate based on skill usage.

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

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.

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)

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)

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

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

Export sessions to JSON or JSONL for backup or migration.

Exports all matching sessions with full detail (including skills, tags, artifacts). 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).

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.

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.

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

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.

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

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

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

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)

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

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 (generic; details in debug log)

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, mcp_installed, mcp_tested, mcp_accepted, status (ok|mismatch|undetermined|disabled|internal_error), note.

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.

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.

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.

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