PMB AI

Improvement D (mem0-style): LLM extracts atomic facts from recent events. Each fact becomes a new searchable event. Stronger than reflections for direct lookup queries. Idempotent - skips events that already have facts.

Aggregate user recall feedback. Returns useful_rate and top flagged-wrong events. This is the real-user health metric.

Find files that are often modified together with the given file. Based on git commit co-occurrence.

Get commit history for a specific file.

Pull procedural lessons (project rules / gotchas) relevant to a topic. Use this BEFORE making a project-shaping choice - picking a library, setting up tooling, choosing an approach - to see what worked or failed before. Lessons are short rules captured from prior corrections / failures ("this repo uses pnpm, never npm", "Postgres pool size must stay below 30"). They override default behaviour. Each result includes a `surface_id`. After acting on a lesson, call mark_lesson_followed(surface_id) - the self-improvement loop uses follow-rate to prune dead lessons. Args: query: topic to filte…

Archive a memory. Not deleted, can be restored.

Return all subfacts linked to a parent event (Improvement P). Useful after recall surfaces a main fact: call this to get the related atomic details (time, advice, warnings, etc.).

Co-occurrence neighbors of an entity. Useful for 'what relates to X'.

Counts of entities and edges in this workspace's association graph.

Most-mentioned entities. kind = 'file' | 'tech' | 'concept' or None.

Get trend of self-test accuracy over time. Returns 'stable' / 'degrading' / 'improving' / 'insufficient'.

📄 Extract text from a PDF and persist it as searchable memory. Each page is chunked (~1500 chars) and written as a fact. The agent can then recall any passage via the usual `recall()`. A re-ingest of the same file is a no-op (idempotent via SHA1). Use when the user says: • "read this PDF and remember it" • "remember this document" • "index <some file>.pdf" • "summarise this paper" (call index_pdf first, then recall) Returns: {file, source_hash, n_pages, n_chunks, duration_ms, ...}

📂 Index a code project's structure - per-file symbols, imports, languages - so the agent can recall things like "where is the auth flow", "which files import LanceDB", "show me the recall pipeline". Respects .gitignore. Idempotent per file (SHA1). Safe to re-run. Use when the user says: • "remember the project structure" • "index this repo" • "scan the project" • "remember how the code is organised" Returns: {project_name, n_indexed, n_skipped, by_language, ...}

📊 Earned Memory: which lessons actually HELP outcomes (not just which were read or followed). Joins each surfaced lesson to the OUTCOME of the turn it was active in - tests pass/fail, red->green, build, deploy (no LLM) - and returns per-lesson success_rate, lift vs the no-lesson baseline, and churn. Use to spot dead-weight or HARMFUL rules (negative lift). Worst lift first.

List narrative arcs in the current workspace.

List goals (optionally filter by status).

List the most recent active events in the workspace.

Confirm whether a previously surfaced lesson actually changed your behaviour on the current task. Call this AFTER acting on a lesson - the self-improvement loop uses this signal to identify useful vs dead lessons. Args: surface_id: the `surface_id` field returned with the lesson followed: True if you followed the lesson, False if ignored note: optional one-line explanation (esp. useful for ignored) applicable: False if the lesson was unrelated to this task

Get a structured OVERVIEW of everything memory knows about a topic. Call this when (re)starting work on a project, feature, person, or decision area to get the big picture in ONE call - instead of several recall() calls. Returns key facts & decisions, lessons, failures, open goals, a timeline, and related topics, all from stored memory. Use it at the start of a task to get up to speed on prior context.

Pin a memory: max importance, never auto-archived.

Improvement F (PMB-unique): during sleep, LLM predicts likely questions and pre-runs recall. Future near-identical queries get instant (~3ms) responses via cosine match. Run periodically (e.g. once per day) for active workspaces.

⭐⭐⭐ Call this ONCE at the START of any substantive user task. Auto-detects what the task is about and pre-loads everything you'd need to act on it - in ONE call. Replaces 4-5 separate recall/overview/list_goals/recent_activity calls. Returns whatever's relevant for the message: • project_context - full project_overview if a known project is mentioned (LoadGuard / LeanBoard / PMB / …). Includes lessons (RULES to follow), decisions, open goals, recent activity, related entities. Surface-logged. • active_arcs - narrative arcs the project is currently living in (e.g. "Postgre…

⭐ Use at the START of any project work - returns the FULL project context in ONE call, sourced from the entity graph (not recall): • All key facts about the project (top by importance) • LESSONS - procedural rules you MUST follow ("use pnpm not npm") • DECISIONS - past architectural / design choices • OPEN GOALS still in flight • Recent completed work + activity timeline • Related entities (tech stack, people, files mentioned with it) Faster + more complete than overview() because it walks the entity-graph directly. Best for known projects with a strong entity (e.g. project_overv…

🗺️ Pull a project's STRUCTURE straight from memory - no filesystem scan. Returns the file/module map captured by `index_project`, enriched with the one-line purpose per file from `track modules` and the latest change intents from `track changes`: • languages - file count per language • tree - files grouped by top-level directory, each with its purpose + symbol count • key_modules - the most significant files (purpose + symbol count) • recent_changes - latest commit intents Use this to learn how a project is laid out / where things live BEFORE reading files. Complements project_o…

Search PMB long-term memory. CALL THIS FIRST when user asks about: - past decisions (why did we choose X, what port did we set) - project history (when did we, what happened with) - people (who is X, what did Alice say) - any fact the user might have recorded earlier Trust results with score > 0.2 - they are the user's recorded history, more authoritative than inferring from code/docker/env. Optional `project`: scope results to a single project (a filter over the one user memory - not a separate store). Leave empty to search everything. Returns structured pack with results, each containing …

DEEP recall - explicitly opt into the slow, thorough path. Unlike `recall` / `recall_smart` (fast, local, bounded), this ATTEMPTS LLM query-decomposition (RAG-Fusion: split → retrieve each → fuse) and may take several seconds. It is still bounded by a deadline so it cannot hang, and falls back to a normal local recall if the LLM backend is unavailable. Use ONLY when a hard multi-hop question genuinely needs it and the latency is acceptable - never for routine lookups.

💡 BEFORE re-exploring the codebase, check if a PAST session already figured this out. Returns memoized conclusions matching `intent`, each with a freshness check: • `fresh: true` -> every source file is unchanged, trust the conclusion and skip the re-reading entirely. • `fresh: false` -> `stale_files` lists what changed since; re-check ONLY those, reuse the rest. This reuses an earlier exploration's OUTPUT instead of re-deriving it from scratch, which is where the tokens/turns actually go. Call it at the start of a task like "how does X work / where is Y handled".

Auto-escalating recall, but FAST and deadline-bounded. Starts with a normal local recall; if confidence is low it escalates only with cheap local steps (wider pool + a local rerank when that model is already warm). It NEVER blocks on an LLM / Claude CLI on this path and always returns within `recall.smart_deadline_ms` (default 15s), returning the best result found so far if the budget is hit. The result includes an `escalation` field (stages run + why it stopped) so you can see there's no point re-querying. For routine lookups use `recall`; for a genuinely hard multi-hop question where you ac…

Improvement Q: working memory dump - instant, no search. Call THIS instead of recall for questions like: "what did we just do?" "what did we just do?" "show me the last edits" "what happened in the last hour?" Returns chronological list (newest first) of activity events. Free of BM25/vector overhead - pure SQL by timestamp. Filters: minutes: lookback window (default 60) actor: 'agent' / 'user' / 'system' / None kind: 'action' / 'edit' / 'tool_call' / etc.

Improvement Q: log a working-memory activity. Use AFTER any significant action: you made an edit, ran a tool, gave a recommendation, decided something, completed a step. Lighter than record_fact - session-scoped, working tier (3-day decay). Examples: record_activity("Implemented typo correction with 5 algorithms", kind="edit") record_activity("Recommended ER visit for broken arm", kind="recommendation") record_activity("Ran test suite, 82/82 passing", kind="tool_call") record_activity("Finished v2.6 architecture review", kind="completed") actor: 'agent' (default - AI's own action) …

⚡ PREFERRED for ANY message with multiple facts. Stores N atomic facts / goals / activities / milestones / fact_trees in a SINGLE call. WHY this matters: each separate MCP tool call costs the agent ~3-5 seconds of LLM thinking (planning the next call). 11 separate record_fact calls = ~55 seconds. ONE record_batch call = ~5 seconds. ALWAYS prefer this over multiple record_fact/record_goal calls. Schema for `items` - list of operation dicts, each with a `type`: {"type": "fact", "content": "...", "importance": 0.7} {"type": "lesson", "content": "...", "project": "PMB"} …

Record code content. For Python, AST entities (functions, classes, imports) are auto-extracted into the graph layer (Improvement J).

💡 AFTER researching something in the codebase (reading/grepping several files to reach a conclusion), memoize it so a FUTURE session can reuse the conclusion instead of re-deriving it. Stores the intent, the conclusion, and each source file's current content hash. `recall_exploration` later replays it and tells you which sources are unchanged vs changed. Record only GROUNDED conclusions you actually reached from the listed files. Args: intent: the question/goal you researched ("where is auth handled"). conclusion: what you concluded, concise and self-contained. files: the source…

STORE a fact for long-term recall. CALL THIS PROACTIVELY whenever the user mentions: - Personal events ("I broke my arm", "ate pizza yesterday") - Health/medical ("I have an allergy", "doctor said X") - Decisions ("we chose Postgres", "switched to Vite") - Preferences ("I prefer dark mode") - People ("my wife is Anna", "met Caroline at conf") - Schedule ("flying to Paris next week") - Anything the user might want to recall later Rules: - One atomic fact per call (separate calls for separate facts) - FUTURE INTENT → goal, NOT fact. If the user states what will be done NEXT ("remember we'll …

Improvement P: store a main fact + multiple linked sub-facts in ONE call. Use whenever ONE user statement contains MULTIPLE atomic data points worth remembering separately. Common cases: - User describes an event + you give advice: main: "On May 23, 2026, user fell and broke arm" subfacts: ["Time: 18:52", "Recommended ER visit", "Avoid driving, ice 15min, remove rings", "911 if: numbness, bleeding, deformation"] - User states a goal + you list steps: main: "User decided to migrate from MySQL to Postgres" subfacts: ["Reason: JSONB support", "Targ…

Improvement R: create a goal/intent (12-th semantic layer). Use when user states a goal, plan, or FUTURE intention - record it HERE, not as a fact: "I want to learn Rust by the end of the year" "Need to ship v1.0 by Q3" "Plan: refactor auth first, then frontend" "remember that next we'll do X" / "next steps are X" A plan about what to do NEXT is a goal, never a fact: facts are settled state, goals resurface via prepare()/open-goals so the agent remembers what to do next session. Goals have status (pending/in_progress/done/cancelled), optional hierarchy (parent_goal_ulid), and option…

Record an image (screenshot/diagram) in memory (Improvement J). `description` is the searchable text - make it specific. Set `encode_clip=True` for cross-modal text→image search (requires open_clip or sentence-transformers; gracefully degrades). Returns the ulid of the image event.

⭐ Use for SINGULAR personal attributes that CHANGE over time. When the user states a fact about themselves (or a person/thing) where there's exactly ONE current value, and that value can change later - use this instead of record_fact. Examples that fit: • "I live in Warsaw" / "moved to Warsaw" → record_keyed_fact("user", "city", "Warsaw") • "I work at Anthropic" / "now working at Anthropic" → record_keyed_fact("user", "employer", "Anthropic") • "my dog is now Pixel" (renamed) → record_keyed_fact("user_dog", "name", "Pixel") • "my phone number is +380..." → record_keye…

Improvement R: record a milestone in a named state-chain. Use to track EVOLUTION of any tracked thing - "X became Y because Z". Example: record_milestone( chain_name="architecture_layers", title="11 layers (added activity log)", state={"count": 11, "previous_count": 10, "added": "activity"}, triggered_by_ulid=<ulid of the implementation event>, ) Later `chain_history("architecture_layers")` returns the full sequence: 6 → 7 → ... → 11, with the reason at each step. Auto-links to the previous milestone in the same chain (no need to specify previous_ulid manually).…

Record real recall feedback for an event. verdict: 'useful' | 'wrong' | 'irrelevant'. Useful events get importance boost, wrong/irrelevant get a small decrease, expected_ulid (if given) gets a stronger boost. This is the primary signal for adaptive importance - prefer it over the synthetic self-test.

PMB v2 sleep operation: LLM reflects on recent un-reflected events. For each event the LLM extracts: - significance (why it matters) - might_answer (what questions it helps answer) - causation edges to related recent events - bridge entities (linked back to source for graph search) Returns counts of reflections + edges added.

Store a Q/A interaction in memory. Args: query: the user query / question response: the agent response / answer importance: 0..1 importance score (default 0.5) session_id: optional session identifier for grouping

Quantify memory health: system asks itself questions from old memories. Returns accuracy metrics (acc@1, acc@3, acc@5) and list of failures. If apply_adaptive=True, failed events get importance boost.

Cross-modal image search. Encodes the query via CLIP text encoder and finds nearest stored image embeddings. Falls back to plain-text recall (filtered to image events) if CLIP is not installed.

Re-orient in a long session: a digest of what was decided / done / learned so far THIS session. Call this when you've lost the thread - after your own context window compacts, or many turns into a long task - instead of re-asking the user what you already did. Returns decisions, completed work, lessons, failures and goals from the current session (or the last `minutes`). PMB is your durable memory across your own context limits.

Get current active session info (or None).

End the current session. Returns the closed session's info.

Start a new memory session. Used to group related events.

Chronological dump of CURRENT session events. Use for post-mortem 'summarize this session' style questions.

Get workspace and memory statistics.

Capture recent git commits into memory. Pulls commits since last sync (or since the given timestamp), stores each as a 'git' event with full metadata (sha, author, files changed, diff stats).

Update goal status / progress. Creates a goal_update event so the full history of changes is preserved.

Quick: last N events of any type from current session. Use to answer 'what were we doing?' / 'recap of this session'. Instant, no search.

Identify the current PMB workspace. Useful when multiple MCP clients share one workspace - confirms which events.db file is in use.