Skip to main content
Your persistent memory across all AI tools. This is the unified read tool — it handles search, file history, and entity overview based on which parameters you provide.
v0.7.0: recall replaces the previous recall + recall_file + list_entities tools. Mode is auto-detected from params.

​
Modes

​
Search (provide query)

Returns memories ranked by a composite score of relevance, heat, momentum, and importance. 
{
  "query": "Supabase connection pooling",
  "layer": "caveat",
  "max_tokens": 3000
}

​
File history (provide path)

Returns complete edit history of a file across all sessions, with per-edit user-intent context. 
{
  "path": "server.ts"
}
When both path and query are provided, results from file history and memory search are merged.

​
Entity overview (no params)

Returns entity list sorted by momentum — the cheapest “what do I know?” primitive. 
{}

​
Parameters

​
Search mode

​
query
string
What you want to remember. Free-text, entity name, or FTS5 MATCH expression.
​
entity_name
string
Narrow results to a specific entity.
​
layer
string
Filter by memory layer. Accepts aliases (e.g. warnings -> caveat).
​
altitude
string
Filter by cognitive altitude: mission, strategy, architecture, implementation.
​
mem_type
string
Filter by memory type: question, comparison, decision, work, outcome, learning, note.
​
mem_state
string
Filter by lifecycle state: open, decided, in_progress, done, stalled, parked, superseded.
​
thread_id
string
Filter by thread ID — returns all memories in a decision chain or session group.
​
band
string
Filter by heat band: hot, warm, cold, frozen.
​
max_tokens
number
default:"2000"
Approximate token budget. Iteration stops when this budget is consumed or limit is reached, whichever comes first.
​
limit
number
Hard cap on number of memories returned.
​
offset
number
default:"0"
Skip this many top results (pagination). Use has_more from prior response to decide next offset.
​
mark_accessed
boolean
default:"true"
Set false for preview / listing queries that should not bump heat scores.

​
File history mode

​
path
string
File path substring to match against edit history. Can be a filename (search-services.ts), partial path (src/db/), or full absolute path.

​
Ranking (search mode)

Memories are ranked by a composite score: 
score = 0.45 * relevance + 0.25 * heat + 0.15 * momentum + 0.15 * importance
FactorWeightSource
Relevance45%FTS5 BM25 score + LIKE match
Heat25%Ebbinghaus decay since last access
Momentum15%Entity activity frequency
Importance15%User-assigned or auto-inferred

​
Response

​
Search mode

Each memory in the response includes:
  • match_reasons — array explaining why this memory ranked (e.g. content_match_fts, entity_name_match, heat:hot, pinned, caveat_protected)
  • score_breakdown — individual scores for transparency
  • has_more — boolean indicating if more results exist beyond the current page
  • stopped_by — whether iteration stopped at tokens, limit, or end

​
File history mode

FieldDescription
paths_matchedList of file paths that matched the substring
total_editsTotal number of physical edits recorded
first_edit / last_editDate range of edit history
sessions_involvedNumber of distinct sessions that edited this file
daily_breakdownEdits per day, grouped by operation type
user_intentsDistinct user-intent snippets, ordered by recency
linked_memoriesRelated memories with entity name and preview

​
Entity overview mode

Each entity includes: name, kind, memory_count, layer breakdown (goal_count, caveat_count, etc.), momentum_score.
Dual search: Recall uses both FTS5 full-text search (BM25-ranked, trigram tokenizer) and LIKE fallback, merging and deduplicating results. This ensures both exact and fuzzy matches are found, including Japanese text.

​
Migration from pre-v0.7

Old callNew equivalent
recall({ query: "..." })recall({ query: "..." }) (unchanged)
recall_file({ path_substring: "server.ts" })recall({ path: "server.ts" })
list_entities({ kind: "project" })recall({}) (no params = entity overview)