Store a new memory with automatic embedding and deduplication.

Primary write path — call after a significant decision, tricky bug fix, or new pattern discovery. Auto-generates embeddings via Ollama (1024d) or local all-MiniLM-L6-v2 (384d fallback). Detects project scope from CWD. Deduplicates at cosine similarity > 0.82 — boosts existing memory instead of creating duplicates.

Read-only: no. Creates or updates a row in LanceDB. Triggers background consolidation if interval has elapsed (non-blocking, fire-and-forget).

Args: content: Full memory content in Markdown. Required. First 200 chars auto-summarized if summary is omitted. summary: One-line summary shown in recall results. Default: auto-generated. type: 'episodic' (session captures, decay 0.15/day), 'semantic' (extracted knowledge, decay 0.03/day), or 'permanent' (decisions/ conventions, never decays). Default: 'episodic'. scope: Isolation prefix. Auto-detected from project config or CWD path hash. Use 'global' for cross-project memories. weight: Initial importance 0.0–1.0 (default 0.5). Decays exponentially per type's decay_rate. Frequently-accessed memories get counteracting boost. tags: Optional labels for filtering, e.g. ['testing', 'api', 'pitfall']. embedding: Pre-computed vector. Auto-generated from first 2000 chars of content if omitted. Padding/truncation handled automatically. diff_text: Optional unified diff for code-change memories. diff_files: Optional list of changed file paths. error_trace: Optional stack trace for error/bug memories.

Returns: dict: {'id': <memory_id>, 'summary': , 'action': 'created'} On dedup match: action='boosted' with existing ID and similarity score.

Search for relevant memories using vector search and six-factor scoring.

Primary read path — call before every non-trivial response to surface past decisions, patterns, and pitfalls. Combines vector similarity (LanceDB ANN), weight decay, recency, scope match, access count, and type boost into a single relevance score.

Read-only: yes. No side effects. May trigger background consolidation (non-blocking) if interval has elapsed.

Args: query: Natural language description of what you're looking for. 5-15 words works best. E.g. "how do we handle API auth?" scope: Scope to search. Auto-detected from project config or CWD. Use 'global' to search only cross-project memories. token_budget: Maximum tokens for returned content across all results (default 2000). Results accumulated until budget exhausted. min_score: Minimum final relevance score 0.0–1.0 (default 0.3). Score ≥ 0.6 = directly applicable, 0.4-0.6 = hint/context, < 0.4 = ignore. limit: Maximum candidates to score from ANN search (default 30). type_filter: Restrict to specific memory types, e.g. ['semantic', 'permanent'] to exclude ephemeral session captures.

Returns: list[dict]: Scored, deduplicated memory objects sorted by final_score descending. Embeddings and binary fields stripped. Empty list if no results above min_score.

Archive a memory by setting its weight to zero.

The memory row remains in LanceDB for audit but is excluded from all recall results (weight=0 → weight_score=0 → final_score=0). Use for outdated or incorrect memories. For permanent deletion use delete_memory with permanent=True. For bulk cleanup use purge_memories.

Read-only: no. Mutates the memory's weight to 0. Reversible via update() by setting weight back to a non-zero value.

Args: id: Memory ID (returned by remember() or recall()).

Returns: dict: {'ok': True, 'id': , 'action': 'forgotten'}

Delete a memory — soft (archive) or hard (permanent removal).

Two modes:

• Soft-delete (default, permanent=False): sets weight=0. Memory stays in LanceDB for audit trail but never surfaces in recall. Reversible via update().

• Hard-delete (permanent=True): removes the row from LanceDB entirely. Irreversible. The ID cannot be reused.

Read-only: no. Mutates or removes a row. Prefer forget() for routine archiving; reserve permanent=True for data that must be erased.

Args: id: Memory ID to delete. permanent: False = soft-delete (weight=0), True = remove row from LanceDB permanently. Default: False.

Returns: dict: {'ok': True, 'id': , 'action': 'soft_deleted'} or {'ok': True, 'id': , 'action': 'deleted_permanently'}

Selective bulk delete of memories by type, scope, or age.

Removes matching rows from LanceDB permanently. Always use dry_run=True first to preview what would be deleted — this is irreversible.

Read-only: no. Irreversibly removes rows from LanceDB. At least one filter is required to prevent accidental full-table deletion.

Args: scope: Only delete memories in this scope (e.g. 'proj:abc123'). type: Only delete memories of this type — 'episodic', 'semantic', or 'permanent'. older_than_days: Only delete memories older than N days. dry_run: If True, preview count without deleting (default False). Always test with dry_run=True first.

Returns: dict: If dry_run: {'dry_run': True, 'current_total': , 'filters': {...}}. If executed: {'ok': True, 'deleted': , 'remaining': }.

Find memories due for consolidation across the 3-phase pipeline.

Returns structured candidate lists for the host model (Claude, DeepSeek, GPT, or local Ollama) to process. The server prepares prompts and candidates; the host does the reasoning and writes results back via remember()/update()/forget().

Phases:

1. Extract (3 days): episodic → host extracts conclusions → semantic

2. Merge (7 days): similar semantics → host merges → permanent

3. Archive (30 days): low-weight memories → weight = 0

Read-only: yes. Only returns candidates. The host model must explicitly call remember/update/forget to persist consolidation results.

Args: scope: Scope to consolidate. Auto-detected if omitted.

Returns: dict with keys: - to_extract: list of {memory, prompt} — episodic memories to extract - to_merge: list of {memories, prompt, similarity, count} — clusters - to_archive: list of memories with weight < 0.1 - to_decay: list of episodic memories > 7 days - meta: {total_candidates, scope, timestamp}

Return memory store statistics — total, by type, weights, counts.

Read-only: yes. No side effects. Call at session start to check if relevant context exists, or before purge to confirm scope contents.

Args: scope: Optional scope filter. Returns global stats if omitted.

Returns: dict: {total_memories, episodic_count, semantic_count, permanent_count, avg_weight, total_relations, conversation_count, last_consolidation}

Retrieve a single memory by its ID with all metadata.

Read-only: yes. Use to inspect a memory returned by recall() or to verify the state of a memory after update().

Args: id: Memory ID (returned by remember(), recall(), or consolidation).

Returns: dict: Full memory object (content, type, weight, tags, timestamps, embedding excluded), or None if not found.

Update memory metadata — tags, weight, needs_review flag, etc.

Cannot change the embedding vector or id (filtered for safety). Use after consolidation or to manually adjust a memory's importance.

Read-only: no. Mutates memory row in LanceDB.

Args: id: Memory ID to update. fields: Dict of field→value pairs. Allowed: tags, weight, summary, content, needs_review, boost_factor, type, scope. Blocked: embedding, id (silently ignored).

Returns: dict: Updated memory object (embedding excluded), or {'error': 'not found'} if ID doesn't exist.

Return memories flagged for review — contradictions, stale data, etc.

The consolidation pipeline flags memories when it detects conflicts, contradictions, or data that looks stale. Use this to surface issues that need human attention.

Read-only: yes. No side effects. Call periodically to catch data quality issues.

Returns: list[dict]: Memory objects with needs_review=True. May be empty.