Skip to main content

​
Overview

The memory context command retrieves a summary of available memories formatted for injection into agent prompts. This is typically used by hooks and integrations to provide agents with relevant context at session start.

​
Syntax

memory context [OPTIONS]

​
Options

​
--project
flag
Filter to current project only (uses current directory name).
​
--source
string
Filter by source (e.g., cursor, claude, codex).
​
--limit
integer
default:"10"
Maximum number of memory pointers to return.
​
--query
string
Semantic search query for filtering memories by relevance.
​
--semantic
flag
Force semantic search (requires embeddings). Overrides config.
​
--fts-only
flag
Disable embeddings and use FTS-only search.
​
--show-config
flag
Show effective configuration and exit (doesn’t retrieve memories).
​
--format
choice
default:"hook"
Output format: hook (default) or agents-md.

​
Examples

​
Get context for current project

memory context --project
Output: 
Available memories (12 total, showing 10):
- [Mar 03] JWT expiry set to 7 days [decision] [auth,security]
- [Mar 02] Connection pooling implemented [decision] [database,performance]
- [Mar 01] Rate limiting added [pattern] [api,security]
- [Feb 28] OAuth2 flow complete [pattern] [auth]
- [Feb 27] Fixed null pointer in auth middleware [bug] [auth]
- [Feb 26] API versioning strategy [decision] [api]
- [Feb 25] Error handling pattern [pattern]
- [Feb 24] Database migration approach [decision] [database]
- [Feb 23] Code review guidelines [context]
- [Feb 22] Testing strategy defined [decision] [testing]
Use `memory search <query>` for full details on any memory.

​
Get all memories (no filter)

memory context --limit 20

​
Query-based context

memory context --query "authentication and security" --project

memory context --semantic --project --limit 5

memory context --fts-only --project

​
Agents markdown format

memory context --project --format agents-md
Output: 
## Memory Context

Available memories (12 total, showing 10):
- [Mar 03] JWT expiry set to 7 days [decision] [auth,security]
- [Mar 02] Connection pooling implemented [decision] [database,performance]
...

Use `memory search <query>` for full details on any memory.

​
Show configuration

memory context --show-config
Output: 
embedding:
  provider: ollama
  model: nomic-embed-text
  base_url: http://localhost:11434
  api_key: <redacted>
context:
  semantic: auto
  topup_recent: true
memory_home: /home/user/.memory
memory_home_source: persisted

​
Output Format

​
Default (hook format)

Optimized for agent prompt injection:
  • Date formatted as “Mon DD” (e.g., “Mar 03”)
  • Title with category and tags in brackets
  • Footer with search instruction

​
Agents markdown format

Similar to hook format but wrapped in a markdown section:
  • Starts with ## Memory Context header
  • Same list format
  • Ends with blank line

​
How Context Retrieval Works

​
Retrieval Strategy

The context command follows your config.yaml settings: 
context:
  semantic: auto      # auto | always | never
  topup_recent: true  # also include recent memories
  • semantic: auto: Use vectors if available, fall back to keywords
  • semantic: always: Require embeddings (error if not configured)
  • semantic: never: Always use FTS5 keyword search
  • topup_recent: true: Include recent memories even if not highest-ranked

​
With --query

When you provide a query:
  1. Searches memories using hybrid FTS5 + semantic
  2. Ranks by relevance to the query
  3. Returns top N based on --limit

​
Without --query

When no query is provided:
  1. Returns recent memories (ordered by creation date)
  2. Optionally filtered by project/source

​
Integration Use Cases

​
In agent hooks

Typically used in .cursor/hooks.json, .claude/settings.json, or similar: 
{
  "hooks": [
    {
      "name": "memory-context",
      "command": "memory context --project --limit 10",
      "when": "session_start"
    }
  ]
}

​
In shell scripts

Capture context for custom workflows: 
#!/bin/bash
context=$(memory context --project --format agents-md)
echo "$context" > /tmp/session-context.md

​
With MCP servers

The EchoVault MCP server uses this internally: 
memory mcp
# Uses context retrieval for agent memory injection

​
Filtering Logic

​
By project

memory context --project
Filters to memories where project matches the current directory name.

​
By source

memory context --source cursor
Filters to memories saved by a specific agent/source.

​
Combined

memory context --project --source claude --limit 5
Both filters applied (AND logic).
Use --query when you want context relevant to a specific topic, like starting a new feature: memory context --query "payment API" --project
The --semantic and --fts-only flags override your config.yaml settings for testing. Most integrations should rely on the config file.

Build docs developers (and LLMs) love

Get started for freeTalk to us