| name | memory-query |
| description | Read from the knowledge graph — natural language questions, semantic search, or hybrid search over objects and documents. |
| 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.
Want to write to the graph? Load the memory-graph skill to create, update, or delete objects and relationships.
Query an Emergent project knowledge base using the memory query command.
Rules
- Project context is auto-discovered — the CLI walks up the directory tree to find
.env.local containing MEMORY_PROJECT or MEMORY_PROJECT_ID. If .env.local is present anywhere above the current directory, --project is not needed. Only pass --project <id> explicitly when overriding or when no .env.local exists.
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"
memory query --mode=search --recency-boost 1.0 "recent decisions"
memory query --mode=search --recency-boost 0.5 --recency-half-life 720 "recent changes"
memory query --mode=search --access-boost 0.5 "frequently referenced patterns"
Session Continuation
After each agent query, a session ID is printed:
Session: abc123 (use --session abc123 to continue)
Pass it back to continue the conversation with full history:
memory query "what are the main services?"
memory query --session abc123 "which of those handles auth?"
Sessions are scoped to the project. Only supported in --mode=agent.
Key Flags
| Flag | Default | Notes |
|---|
--mode | agent | agent or search |
--project | from config | Override target project |
--session | — | Continue a previous query session (agent mode only) |
--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 |
--recency-boost | 0 | Boost score by creation recency (0 = off; try 0.5–2.0) (search mode only) |
--recency-half-life | 168 | Half-life in hours for recency decay (default 168 = 7 days) (search mode only) |
--access-boost | 0 | Boost score by access recency (0 = off; try 0.5–2.0) (search mode only) |
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
- To follow up on a previous query, pass
--session <id> to continue with full conversation history
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'
