| name | memory-query |
| description | Query an Emergent project knowledge base using natural language or direct hybrid search. Use when the user wants to search, explore, or ask questions about content in an Emergent project. |
| metadata | {"author":"emergent","version":"2.0"} |
New to Emergent? Load the memory-onboard skill first to set up the project's knowledge graph schema before querying.
Query an Emergent project knowledge base using the memory query command.
Rules
- Never run
memory browse — it launches a full interactive TUI that blocks on terminal input and will hang in an automated agent context.
- Always prefix
memory commands with NO_PROMPT=1 (e.g. NO_PROMPT=1 memory <cmd>). Without it, the CLI may show interactive pickers when no project, agent, MCP server, skill, or agent-definition ID is provided. Do not add this to .env.local — it must only apply to agent-driven invocations.
- Always supply a project with
--project <id> on project-scoped commands, or ensure MEMORY_PROJECT is set.
Modes
Agent mode (default) — AI reasoning over the knowledge graph. Best for complex or multi-hop questions.
memory query "who directed fight club and what are their other movies?"
memory query --project <id> "list all requirements for the auth module"
memory query --show-tools "what are the key relationships between X and Y?"
Search mode — Direct hybrid search (semantic + lexical), no AI reasoning. Best for finding specific content fast.
memory query --mode=search "fight club"
memory query --mode=search --result-types=graph --limit=20 "authentication"
memory query --mode=search --result-types=text "API rate limiting"
Key Flags
| Flag | Default | Notes |
|---|
--mode | agent | agent or search |
--project | from config | Override target project |
--json | false | Machine-readable output |
--show-tools | false | Show agent tool calls (agent mode only) |
--limit | 10 | Max results (search mode only) |
--result-types | both | graph, text, or both (search mode only) |
--fusion-strategy | weighted | weighted, rrf, interleave, graph_first, text_first |
Workflow
- If the user's question is broad or relational -> use agent mode (default)
- If the user wants to find specific documents or objects quickly -> use search mode
- If no
--project is set, the CLI uses the default project from config; ask the user to confirm or specify one if the context is ambiguous
- Use
--output json + --json for downstream processing or to pass results to another tool
Output Format
Agent mode streams the response and prints a final answer. Search mode returns a table (or JSON) of matching objects/documents with scores.
Use --json to get structured output suitable for parsing:
memory query --mode=search --json "authentication" | jq '.[].title'
