Use this to remember key decisions, facts, user preferences, or technical
findings that should be preserved across conversations.

Args:
    content: The insight or fact to remember (be concise but complete)
    category: Type — decision, fact, preference, finding, todo, general
    importance: Priority — low, medium, high, critical
    tags: Comma-separated keywords for retrieval (e.g., "api,auth,v2")
    summary: Optional one-line summary
    entities: Optional comma-separated entities mentioned
    project: Optional project name
    session: Optional session ID

Use this to find previously stored knowledge — decisions, preferences,
technical findings. Call at session start to load relevant context.

Args:
    query: Search term (searches content, tags, and summary)
    category: Filter by type
    importance: Filter by priority
    limit: Max results (default 10)
    max_tokens: Token budget — returns results until budget is exhausted (0 = unlimited)
    project: Filter by project
    session: Filter by session ID
    scope: "project" (default), "session" (current only), "all" (cross-project)

Args:
    insight_id: The ID of the insight to remove

Args:
    project: Filter stats by project
    session: Filter stats by session

Use this to save large content (files, conversation history, code)
that should be accessible without loading into the prompt.

Args:
    name: Unique name for this context (alphanumeric, dots, hyphens, underscores)
    content: The content to store (provide content OR file_path, not both)
    file_path: Path to a file to load as context
    project: Optional project name

Use this to check a context's type, size, and token count before deciding
whether to load it into the prompt.

Args:
    name: Context name to inspect

Args:
    name: Context name
    start: Start line (1-indexed, 0 = from beginning)
    end: End line (1-indexed, inclusive, 0 = to end)

Args:
    name: Context name (must already be loaded)
    strategy: Splitting strategy — auto, lines, paragraphs, headings, chars, regex
    chunk_size: Size per chunk (lines for 'lines', chars for 'chars', tokens for 'paragraphs')
    overlap: Overlap between chunks (lines or chars)

Args:
    context_name: Context name
    chunk_index: Chunk number (0-indexed)
    start: Start line within chunk (1-indexed, 0 = from beginning)
    end: End line within chunk (1-indexed, inclusive, 0 = to end)

Returns only lines matching (or not matching) the pattern.

Args:
    name: Context name
    pattern: Regex pattern to match lines
    invert: If True, return lines that DON'T match the pattern

Args:
    project: Filter by project name (empty = all projects)

Args:
    name: Context name to delete

Auto-selects the best available search method (BM25 > keyword).
Install optional packages for better search: pip install memcp[search]

Args:
    query: Search query
    limit: Max results (default 10)
    source: Where to search — "all" (default), "memory", "contexts"
    max_tokens: Token budget (0 = unlimited)
    project: Filter by project
    scope: "project" (default), "session", "all"

Discovers insights related via semantic similarity, temporal proximity,
causal chains, or shared entities.

Args:
    insight_id: The ID of the insight to start from
    edge_type: Filter by edge type — semantic, temporal, causal, entity (empty = all)
    depth: How many hops to traverse (default 1)

Shows how knowledge is connected in the graph.

Args:
    project: Filter by project (empty = all projects)

Shows candidates for archiving (stale, low-access items) and purging
(archived items past retention period). Items with high importance,
frequent access, or protected tags are immune from archiving.

Args:
    archive_days: Override archive threshold (default from env, 30 days)
    purge_days: Override purge threshold (default from env, 180 days)

Archiving compresses and moves stale items to the archive directory.
Purging permanently deletes archived items past the purge threshold
and logs metadata to purge_log.json for audit.

Args:
    archive: Archive eligible items (default True)
    purge: Purge archived items past retention period (default False)

Decompresses archived contexts and re-inserts archived insights
into the knowledge graph.

Args:
    name: Context name or insight ID to restore
    item_type: "context", "insight", or "auto" (tries both)

Args:
    project: Filter by project (empty = all)
    limit: Max sessions to return (default 20)

Helpful insights get a score boost and stronger edges.
Misleading insights get penalized. This closes the learning loop.

Args:
    insight_id: The ID of the insight to reinforce
    helpful: True if the insight was helpful, False if misleading
    note: Optional note about why

Finds near-duplicate or very similar insights and groups them.
Dry-run — no changes made. Use memcp_consolidate to merge.

Args:
    threshold: Similarity threshold (0 = use default 0.85)
    limit: Max groups to return
    project: Filter by project

Keeps the best insight (most accessed by default), merges tags/entities
from others, redirects edges, and deletes duplicates.

Args:
    group_ids: Comma-separated insight IDs to merge
    keep_id: Which ID to keep (default: most accessed)
    merged_content: Optional override for the merged content