LoreConvo is a local-first persistent memory MCP server that stores structured session summaries in SQLite so context carries across Claude Code, Cowork, Cursor, Codex, and Hermes.
Save sessions: save_session records title, surface, summary, decisions, artifacts, open questions, tags, skills, project, and optional reasoning notes (with optional Haiku summarization and auto-dedup by session ID).
Recall context: get_recent_sessions, get_session, get_context_for, and vault_suggest surface relevant prior work; search_sessions does FTS5 keyword search or Pro semantic/hybrid (LanceDB vector + BM25) search.
Organize projects: create_project, get_project, list_projects group sessions with expected skills, default personas, and persistent instructions; get_skill_history tracks skill usage.
Tag and link: tag_session adds hierarchical personas; link_sessions and get_related_sessions connect related work; pin_session protects sessions from cleanup; set_session_expiry sets or clears expiry.
Anti-patterns: tag_as_anti_pattern, untag_anti_pattern, and get_anti_patterns flag approaches to avoid in future recalls.
Consolidation: consolidate_memories and get_memory_digest build per-project digests (heuristic free, LLM Pro); get_dream_log shows the consolidation audit log.
Data portability: export_sessions, import_sessions, and Pro-only export_for_anthropic move memory between machines or into Anthropic managed-agent format; get_stats and inspect_sessions report usage and let you browse stored data.
Cross-product linking (Pro, with LoreDocs): get_docs_for_session and session_link_doc connect sessions to documents.
Admin: loreconvo_onboard sets up workspace config; get_tier/vault_set_tier check and activate Free vs Pro; rebuild_index rebuilds the semantic index; get_server_info reports MCP version compatibility.
Your memory follows your identity, not your tool — with your consent.
LoreConvo is the only AI memory that carries your context across Claude Code, Cowork, Codex, Cursor, and Hermes Agent. One install, one memory, everywhere you code.
Install directly from Claude Code's plugin marketplace, or via PyPI:
uvx --from loreconvo[server] loreconvo
LoreConvo works across Claude Code, Cowork, Cursor, Codex, and Hermes -- the same memory layer, no matter which client you reach for. When you switch mid-project, your context travels with you automatically.
Most tools wall off memory by machine or workspace. LoreConvo stores everything locally in a SQLite database you own, and surfaces it wherever you are. Capture happens two ways: explicitly via the save tools, or automatically at session end if you install the optional hooks. Either way, you can inspect, edit, or delete any memory at any time.
LoreConvo puts you in control: automatic capture only runs if you choose to install the session hooks, every save is inspectable, and you can delete any memory at any time.
Every memory shows you exactly where it came from — which surface captured it, when, what project context it belongs to, and which skill generated it. No mystery. Full provenance.
LoreConvo stores everything in a SQLite database on your own machine. Your data stays local unless you explicitly enable optional AI summarization (off by default) by setting LORECONVO_ANTHROPIC_API_KEY, which sends a transcript excerpt or summary to the Anthropic API using that key. LoreConvo never reads the generic ANTHROPIC_API_KEY. No cloud accounts. No vendor with access to your session history.
Your sessions live in ~/.loreconvo/sessions.db -- a file you own, can back up, and can delete whenever you want.
LoreConvo captures two types of memory for each session:
Episodic memory: what happened -- summaries, artifacts created, open questions left behind
Semantic memory: what was decided -- stable conclusions about the project that persist across sessions
Together these give Claude a structured, searchable record of your project's history, not just a pile of chat transcripts.
Related MCP server: ai-memory
LoreConvo's FTS5 search is benchmarked against a 60-session synthetic corpus (6 topic areas, 36 labeled queries).
Variant | Recall@5 | MRR |
FTS5 + compound token expansion (default) | 88.9% | 0.875 |
FTS5 baseline (no expansion) | 72.2% | 0.708 |
Compound token expansion (camelCase / snake_case query preprocessing) lifts Recall@5 by +35.7 pp on queries using technical identifiers like autoSave, pipeline_tracker, and get_context_for.
Full benchmark report | Reproduce
One command to install:
bash install.shThis creates a virtual environment, installs dependencies, and verifies everything works. No system Python changes, no manual pip commands.
Using the Claude Agent SDK directly? git clone the public repo and point the SDK's local-directory plugin loader at it -- the repo root is a self-contained plugin directory (.claude-plugin/plugin.json + .mcp.json). No separate SDK-installable bundle exists or is needed.
Start a session with the plugin loaded:
claude --plugin-dir /path/to/loreconvoOr load it inside an existing session:
/plugin add /path/to/loreconvoReplace /path/to/loreconvo with wherever you saved the source folder.
After making code changes, use /reload-plugins to refresh without restarting.
Once loaded, Claude has access to all 40 LoreConvo MCP tools automatically. Ask Claude to "save this session" or "recall what we discussed about X" and it will use the tools on its own.
Click the + button next to the prompt box
Select Plugins
Select Add plugin
Browse to the loreconvo source folder
Important: Shared Database Access
Cowork runs in a sandboxed VM and can't see your Mac's filesystem by default. To read sessions saved by Claude Code, ask Claude in Cowork:
"Mount my ~/.loreconvo folder"
Once mounted, Cowork reads and writes to the same database as Claude Code. Sessions saved in Code appear instantly in Cowork.
Chat doesn't support plugins, so LoreConvo provides a one-command bridge. Run this in your terminal:
bash export-to-chat.shThis exports your last session and copies it to your clipboard (macOS). Switch to Chat and paste (Cmd+V). Chat instantly has the context from your Code or Cowork session.
To search for a specific session:
bash export-to-chat.sh "tax prep"The core value of LoreConvo is that context persists across Claude surfaces automatically. Here is the full chain:
Claude Code (~/.claude/settings.json via `claude mcp add`)
|-- SessionEnd hook --> auto_save.py --> ~/.loreconvo/sessions.db
|-- SessionStart hook <-- auto_load.py <-+
|
Cursor (.cursor/mcp.json) <--MCP-----+
Codex (~/.codex/config.toml) <--MCP-+
Hermes Agent (~/.hermes/config.yaml) <-MCP-+
Cowork (MCP-native execution env) <--+
All surfaces: save_session / get_recent_sessions / search_sessions
Claude Chat (web)
|-- export-to-chat.sh --> clipboard --> paste into ChatClaude Code is the primary surface. The hooks run automatically:
When a session ends, auto_save.py captures the conversation and saves a structured summary (decisions, artifacts, open questions, tags) to the local SQLite database.
When a new session starts, auto_load.py queries the database, scores recent sessions by signal quality, and injects the most relevant context into the session as system context. Sessions with open questions and decisions score highest; low-signal sessions are filtered out. It also indexes any MEMORY.md found in the project directory (see MEMORY.md Auto-Indexing below).
Cursor connects via .cursor/mcp.json in the project root -- the same MCP protocol as Claude Code. See INSTALL.md for setup details.
OpenAI Codex connects via ~/.codex/config.toml using a [mcp_servers.<name>] section. See INSTALL.md for setup details.
Hermes Agent connects via ~/.hermes/config.yaml under the mcp_servers: key. See INSTALL.md for setup details.
Claude Chat (web) does not support plugins. The export-to-chat.sh script bridges the gap: it exports your most recent session to your clipboard so you can paste it directly into Chat. This gives Chat the same context that Code would have loaded automatically.
The result: when you switch surfaces mid-project, you never have to re-explain what you were doing.
LoreConvo works through MCP tools when they are available and falls back to bundled scripts automatically when they are not. Your sessions are safe regardless of MCP status -- the same save, search, and recall operations work either way. You do not need to configure anything; the plugin skill handles the switch silently.
LoreConvo projects are persistent workspaces -- every session, decision, and artifact from your work on a project is searchable from any Claude surface.
# Create a project workspace
create_project("my-api", "REST API project", expected_skills=["openapi", "python"])
# Add persistent project instructions (optional)
create_project(
"my-api",
description="REST API project",
instructions="Python 3.10+, SQLite only. No cloud dependencies. Deploy via Docker."
)
# See recent sessions, skill usage, and open questions for the project
get_project("my-api")
# Search scoped to the project
search_sessions("auth design", project="my-api")Project Instructions (optional): When you create a project, you can store persistent instructions or constraints that Claude will see at session start. This is useful for enforcing project-wide standards without repeating them in every CLAUDE.md file. Instructions are displayed in the auto-load context before recent session summaries.
Used with LoreDocs, LoreConvo forms a portable project workspace for all of Claude -- session memory AND structured knowledge, entirely on your machine. Where cloud AI workspaces tie you to one ecosystem, the Lore pair works across every Claude surface you already use.
If your project has a MEMORY.md file, LoreConvo automatically indexes it at every session start. The contents become searchable alongside your regular sessions via search_sessions.
This means Claude can recall project conventions, team notes, or architectural decisions from MEMORY.md without you having to mention them. Search results from MEMORY.md are tagged memory_md and have source='file_memory' so you can tell them apart from regular session entries.
Which directory is scanned?
By default, LoreConvo scans the directory where Claude Code is running (the current working directory). To point it at a different directory, pass LORECONVO_PROJECT_PATH as an env flag in your claude mcp add --scope user command:
"--env=LORECONVO_PROJECT_PATH=/Users/YOUR_USERNAME/projects/my_project"Replace YOUR_USERNAME and my_project with your actual values. Use the full absolute path -- do not use ~ or $HOME.
Filtering MEMORY.md entries in search results
To include MEMORY.md entries in a search, use search_sessions normally -- they appear automatically. To see only MEMORY.md entries, filter by tag:
"Search LoreConvo sessions tagged memory_md for 'database conventions'."
The index is updated each time a session starts (idempotent -- no duplicates accumulate).
After installing, verify LoreConvo is working by asking Claude:
"Run
get_recent_sessionsand show me the results."
If you see a list of sessions (or an empty list if this is your first time), LoreConvo is connected. If you get an error about missing tools, re-run bash install.sh and reload the plugin.
For hooks verification (Claude Code only):
"Check if LoreConvo auto-loaded any context at the start of this session."
If the SessionStart hook is working, Claude will have received context from your recent sessions automatically.
For the best experience, add the following snippet to your ~/.claude/CLAUDE.md (global) or your project's CLAUDE.md. This tells Claude how to use LoreConvo consistently across sessions.
## LoreConvo (persistent session memory)
At session start:
1. Call `get_recent_sessions` to check for recent context relevant to the current work.
2. Use this context to avoid re-explaining things already discussed in prior sessions.
During the session:
- If important decisions are made or domain knowledge is shared, note it for the session summary.
At session end:
- Call `save_session` with a summary of what was accomplished, key decisions, open questions,
and any artifacts created. Use appropriate tags (e.g., project name, surface).For Cowork users: Cowork does not run hooks automatically. Add instructions to call get_recent_sessions at session start and save_session at session end in your project CLAUDE.md. See COWORK_RESTORE.md for details.
LoreConvo is local-first and free to use. Pro ($8/mo) removes the session limit and unlocks LLM-quality summaries, hybrid retrieval search, and cross-product linking. Everything runs on your machine on either plan -- Pro adds no cloud component.
Free tier search: keyword (FTS5) + recency ordering. Pro tier search: hybrid retrieval -- vector (BGE-small-en-v1.5), BM25 full-text, and recency reranking combined via RRF fusion. Finds sessions by meaning, not just keywords.
Free | Pro ($8/mo) | |
Saved sessions | 50 | Unlimited |
Full-text search (FTS5) | Yes | Yes |
MEMORY.md auto-indexing | Yes | Yes |
Project tagging, session linking, skill history | Yes | Yes |
Auto-load / auto-save hooks | Yes | Yes |
Local-first, no cloud, zero API costs | Yes | Yes |
Related-session discovery | Keyword co-occurrence | Embedding-based (BGE-small-en-v1.5) |
LLM async session summarization | -- | Yes (Claude Haiku, opt-in) |
Hybrid retrieval: vector + BM25 + recency reranking ( | -- | Yes (Pro) |
Cross-product document linking ( | -- | Yes (also requires LoreDocs Pro) |
Team memory -- export/merge sessions across machines | -- | Yes |
Anthropic managed-agent export ( | -- | Yes |
Check your current tier and usage with get_tier. Activate a Pro license with
vault_set_tier.
Automatic session capture: Sessions save at session end and load at session start via Claude Code hooks -- no manual save_session call required
Cross-client memory: Your context follows you across Claude Code, Cowork, Cursor, Codex, and Hermes -- not locked to one IDE or machine
Structured sessions: Captures decisions, artifacts, open questions -- not just raw text; optional reasoning_notes field stores agent reasoning chains
Project organization: Group sessions by project with expected skill sets
Skill tracking: Record which skills were used for smart filtering
Persona tagging: Hierarchical personas for agent-specific memory (e.g., ron-bot:sql)
Full-text search: SQLite FTS5 for fast keyword search across all sessions
MEMORY.md auto-indexing: Your project MEMORY.md is automatically indexed at session start and is searchable alongside regular sessions via search_sessions
LLM async session summarization (Pro): Auto-saved sessions are upgraded to LLM-quality summaries in the background using Claude Haiku. Opt in by setting LORECONVO_ANTHROPIC_API_KEY. A daily cap (LORECONVO_SUMMARIZER_DAILY_CAP, default 100) prevents runaway API spend. Pro tier only.
Embedding-based related session discovery (Pro): get_related_sessions automatically discovers sessions with similar content using BGE-small-en-v1.5 embeddings (cosine >= 0.75). Up to 10 bidirectional auto-links per save, same-project scoped. Free tier gets keyword co-occurrence links. Set LORECONVO_EMBEDDING_LINKS=0 to disable embedding links.
Cross-product document linking (Pro): Automatically discovers and links the LoreDocs documents most relevant to any session, and vice versa. Uses two new tools: get_docs_for_session and session_link_doc. Requires both LoreConvo Pro and LoreDocs Pro.
Configurable tool groups: Choose which groups of tools your assistant sees (core, memory, graph, agents, admin) with the configure_tools tool or LORECONVO_TOOL_GROUPS. All groups are on by default. See Tool Groups.
Local-first: SQLite database, no cloud dependency, zero API costs
Free - 50 sessions
Full feature set: auto-load, full-text search, tagging, session linking, export and import
Local SQLite storage -- your data, your machine, no cloud account required
One-click install via the Anthropic Marketplace
Pro - $8/month
Unlimited sessions
Team memory: share sessions with teammates (local-first async export/import, no server required)
Related session discovery and semantic search
Anthropic managed-agents export
LLM-quality session summarization in the background (async)
After checkout, your license key is emailed automatically to the address you used at checkout, usually within a few minutes. Questions: info@labyrinthanalyticsconsulting.com.
LoreConvo provides 40 MCP tools that Claude calls automatically during sessions. The table below shows the most commonly used ones -- see MCP Tool Catalog for the complete reference.
Tool | What it does |
| Save a session summary with decisions, artifacts, and tags |
| List recent sessions, optionally filtered by surface |
| Retrieve a specific session by ID |
| Full-text search across all saved sessions |
| Pull relevant context for a topic (best for "recall" use) |
| Add a persona tag to a session |
| Connect related sessions with a relationship type |
| Find sessions related to a given session |
| Create a named project with expected skills |
| Get project details and associated sessions |
| List all projects |
| See which sessions used a specific skill |
| Proactive suggestions for relevant context to load |
| Check current tier and license key status |
| Set the active tier (free or pro) |
| Export sessions to a portable JSON format |
| Import sessions from a previously exported JSON file |
| Merge related sessions into persistent memory entries (Recall) |
| Inject a condensed memory digest into the current session (Recall) |
| Mark a session to expire and be pruned after a given date |
| Show usage statistics (session count, surface breakdown) |
| Inspect session internals for debugging |
| Export sessions in Anthropic managed-agent format (Pro) |
| Rebuild the LanceDB semantic search index (Pro) |
| Poll the status of an in-progress rebuild_index operation (Pro) |
| First-time setup wizard |
| View the consolidation activity log |
| Retrieve LoreDocs documents linked to a specific session (Pro -- requires LoreDocs Pro) |
| Manually create a link between a session and a LoreDocs document (Pro -- requires LoreDocs Pro) |
| Pin or unpin a session to exclude it from automated cleanup |
| List sessions tagged as anti-patterns (approaches to avoid) |
| Tag a session as an anti-pattern so future recalls flag it |
| Remove an anti-pattern tag from a session |
| Save a structured memory item: a decision, open question, or artifact |
| Query structured memory items by type, project, status, and recency |
| Move a memory item through its lifecycle (retire, answer, wont-answer) |
| Correct a memory item's title, body, tags, or metadata, or move it between projects |
| Store or update a named topic config so an agent auto-loads targeted context at session start |
| Return targeted session context for an agent, using stored or call-time topics |
| Export a Mermaid knowledge graph of sessions and their links |
Python 3.11-3.14
macOS or Linux
mcp and click (auto-installed by install.sh)
LoreConvo is local-first. All data lives in ~/.loreconvo/sessions.db on your machine.
Data collected: Session titles, summaries, tags, surface identifiers, project names, and skill names you provide when saving. No telemetry, usage analytics, or identifiers are collected automatically.
Storage: SQLite database at ~/.loreconvo/sessions.db. No cloud storage. Override the path with the LORECONVO_DB environment variable.
Third-party sharing: None by default. Data leaves your machine only if you enable optional AI summarization by setting LORECONVO_ANTHROPIC_API_KEY, which sends a bounded transcript excerpt or summary to the Anthropic API under that key. Every summarization path (background summaries (Pro), post-turn capture (Pro), and save_session(summarize=True)) uses only this key; the generic ANTHROPIC_API_KEY is never read. Leave it unset and everything stays local.
Retention: Data is retained until you delete it via delete_session or remove the database file manually. No automatic expiry.
Full privacy policy: https://labyrinthanalyticsconsulting.com/privacy
MCP tools not showing up in Claude Code?
Make sure you ran bash install.sh first. The .venv must exist with dependencies installed.
"No module named 'mcp'" error?
The .mcp.json points to .venv/bin/python3 inside the plugin folder. If you moved the folder, re-run bash install.sh.
Cowork can't see sessions saved in Code? Ask Claude to "mount my ~/.loreconvo folder" so Cowork can access the shared database.
If the MCP server is unreachable (e.g., in scheduled tasks or automation scripts), scripts/save_to_loreconvo.py provides the same core operations directly against the SQLite database.
# Save a session
python scripts/save_to_loreconvo.py \
--title "Daily QA run" \
--surface "qa" \
--summary "Ran full test suite. All passing." \
--tags '["qa", "automated"]'
# Read recent sessions
python scripts/save_to_loreconvo.py --read --limit 5
# Filter by surface
python scripts/save_to_loreconvo.py --read --surface code --limit 3
# Search sessions
python scripts/save_to_loreconvo.py --search "tax pipeline"The script auto-discovers the database at ~/.loreconvo/sessions.db (or pass --db-path explicitly). It generates proper UUIDs and writes the same schema as the MCP save_session tool.
Secrets (AWS keys; API keys, passwords and tokens of 16 or more
characters written as name=value or name: value; bearer tokens; JWTs;
PEM private keys) are
now automatically redacted before anything is saved, before
a summary is sent to Claude for summarization, and before results are
returned -- across saved sessions and memory items. A new maintenance
command, loreconvo-scan-secrets, can scan and clean up anything saved
before this update (dry-run by default). Pro users should run
rebuild_index afterwards so the semantic search index is cleaned too.
If it finds a match, rotate that credential -- redacting it here does not
invalidate it elsewhere.
Deleted and expired sessions no longer linger in Pro semantic search
results. If you used semantic search before this update, run
rebuild_index once to clear out any old entries.
Agent context now stays within the requested project. Consolidation status is available when viewing a project without selecting a surface.
The Python fallback now matches recent-session filtering and search ranking. Expiry changes require an explicit timestamp or a request to clear it.
See the full changelog for the complete release history.
Business Source License 1.1 (BSL 1.1) - Labyrinth Analytics Consulting
Free for personal/non-commercial use (up to 50 sessions). Commercial use requires a paid license. Converts to Apache 2.0 on 2030-03-31. See LICENSE for details.
mcp-name: io.github.labyrinth-analytics/loreconvo
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).
Inputs: project (required), mode, surface, max_sessions.
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
Inputs: name (required), description, instructions, default_persona, +1 more.
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.
Inputs: project, days_back, output_path, session_ids.
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).
Inputs: tags, limit, format, project, +2 more.
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.
Inputs: limit, topic, project. Returns: result
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.
Inputs: topic (required), semantic, max_results, include_external. Returns: result
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
Inputs: session_id (required), limit.
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)
Inputs: limit, project, surface.
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
Inputs: project (required), disable, surface.
Get project details including recent sessions and skill usage stats.
Args: project_name: The project identifier
Inputs: project_name (required).
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
Inputs: limit, skill, project, days_back. Returns: result
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.
Inputs: no named parameters.
Get full details of a specific session.
Args: session_id: The UUID of the session to retrieve
Inputs: session_id (required).
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)
Inputs: skill_name (required), days_back. Returns: result
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.
Inputs: no named parameters.
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")
Inputs: no named parameters.
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.
Inputs: file_path (required), dry_run, on_conflict.
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).
Inputs: tag, limit, since, search, +3 more.
Link two related sessions.
Args: from_id: Source session ID to_id: Target session ID link_type: Relationship type - 'continues', 'related', or 'supersedes'
Inputs: to_id (required), from_id (required), link_type.
List all defined projects with session counts.
Inputs: no named parameters. Returns: result
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.
Inputs: name, agents, projects, tag_style.
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": "..."}
Inputs: session_id (required), keep_forever.
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).
Inputs: no named parameters.
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.
Inputs: title (required), summary (required), surface (required), tags, +11 more.
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).
Inputs: query (required), tags, limit, skills, +5 more. Returns: result
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)
Inputs: doc_id (required), vault_id (required), session_id (required).
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
Inputs: expires_at (required), session_id (required).
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.
Inputs: session_id (required), reason, source.
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
Inputs: session_id (required), persona_name (required), relevance_note.
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.
Inputs: session_id (required), reason, source.
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).
Inputs: params (required). Returns: result
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)
Inputs: limit, persona, project, days_back.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 33 tools
Most tools have distinct purposes, but there is some overlap between get_context_for and search_sessions, as both retrieve session content based on queries. However, the former focuses on 'prior decisions and context' while the latter is a general search, so they are mostly distinguishable.
All tool names follow a consistent snake_case and verb_noun pattern (e.g., consolidate_memories, create_project, search_sessions). Even compound names like tag_as_anti_pattern and untag_anti_pattern are logically consistent. No mixing of camelCase or other conventions.
With 33 tools, the set is quite large for a memory server. Each tool serves a distinct purpose, but the overall scope might be overwhelming. The number is borderline high compared to typical well-scoped servers (3-15 tools), though the domain is broad.
The tool surface covers most lifecycle operations for sessions, projects, memory, and anti-patterns. Notable gaps include no explicit delete session tool (though set_session_expiry and pin_session manage lifecycle) and no update project tool. Overall, the set is comprehensive with minor gaps.
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Private memory for AI agents: save and recall facts across Claude Code, Codex, Cursor and ChatGPT.
