How to Save a Graphify Query Result: Complete API and CLI Guide

Use graphify.ingest.save_query_result to persist query outcomes as memory documents, enabling downstream agents like reflect and watch to retrieve and analyze previous results.

When building pipelines with Graphify-Labs/graphify, persisting query outcomes is essential for multi-agent workflows. The save_query_result function in graphify/ingest.py provides the canonical mechanism to store question-answer pairs alongside metadata, making them discoverable for future retrieval and reflection.

Understanding the save_query_result API

The save_query_result function orchestrates four distinct operations to ensure reliable persistence of query results.

Input Validation

According to the source code in graphify/ingest.py, the function first validates that the question and answer parameters are present. It also verifies that any supplied source_nodes parameter is iterable, preventing runtime errors during downstream processing.

Memory Payload Composition

The function constructs a structured dictionary containing:

• question – The original user prompt
• answer – The LLM-generated response or manually supplied string
• outcome – Classification value (useful, dead_end, great, etc.) defaulting to "useful" as verified in tests/test_ingest.py
• source_nodes – Optional list of contributing node IDs
• query_type – Optional tag (e.g., "path_query" or "semantic_query")
• Automatic timestamps and provenance metadata

File Persistence and Indexing

The persistence layer generates a unique filename using a hash of the question/answer content, ensuring idempotency. The document writes as JSON or YAML to the specified memory directory (e.g., tmp_path / "memory"). After writing, Graphify updates its internal index (graphify.store) so that subsequent graphify query or graphify reflect commands can locate the result without filesystem scanning.

Programmatic Usage

Import save_query_result from graphify.ingest to save results within Python applications:

from pathlib import Path
from graphify.ingest import save_query_result

mem_dir = Path("/tmp/my-graphify-memory")
mem_dir.mkdir(parents=True, exist_ok=True)

doc_path = save_query_result(
    question="How does attention work?",
    answer="Attention lets the model focus on relevant tokens …",
    mem=mem_dir,
    outcome="useful",               # optional – defaults to "useful"

    source_nodes=["node-42", "node-87"],
    query_type="semantic_query",
)

print(f"Saved result → {doc_path}")

This call creates a file similar to .../memory/0c23f4d5.json and immediately updates the store index.

Using the CLI

The Graphify CLI exposes identical functionality through the save-result command, forwarding arguments directly to the same underlying function:

graphify save-result \
  --question "What is the capital of France?" \
  --answer "Paris" \
  --outcome useful \
  --memory /home/user/.graphify/memory

This guarantees identical behavior between interactive CLI usage and programmatic Python consumption.

Retrieving Saved Results

Use the symmetrical load_query_result function to access persisted documents:

from graphify.ingest import load_query_result

doc = load_query_result(mem_dir / "0c23f4d5.json")
print(doc["answer"])   # → "Attention lets the model …"

The loader returns the complete memory payload, allowing agents to analyze previous outcomes or build cumulative knowledge bases.

Key Implementation Files

The save functionality spans several critical files in the repository:

• graphify/ingest.py – Core implementation of save_query_result handling validation, payload construction, and file I/O
• tests/test_ingest.py – Test suite confirming correct behavior, outcome handling, and edge-case validation
• tests/test_reflect.py – Integration examples showing how the reflect command consumes saved results
• graphify/cli.py – CLI entry point wiring save-result arguments to the core API

Summary

• Primary API: graphify.ingest.save_query_result validates inputs, builds structured payloads, and persists to hashed filenames
• Storage format: JSON or YAML documents in a configurable memory directory with automatic index updates
• CLI equivalent: graphify save-result command mirrors the Python API exactly
• Retrieval: Use load_query_result to access saved documents programmatically
• Integration: Saved results feed directly into graphify reflect and watch agents for downstream analysis

Frequently Asked Questions

What file format does Graphify use to save query results?

Graphify writes memory documents as either JSON or YAML files, depending on configuration. The files reside in the memory directory you specify (e.g., /home/user/.graphify/memory) and contain complete query metadata including timestamps, source nodes, and outcome classifications.

How does Graphify ensure idempotency when saving results?

The system generates unique filenames by hashing the question and answer content. This deterministic approach prevents duplicate files when the same query result is saved multiple times, while the internal index in graphify.store maintains the latest reference.

Can I customize the memory directory location?

Yes. Both the save_query_result function and the CLI accept a mem or --memory parameter specifying the target directory. The function automatically creates the directory structure if it does not exist, making it safe to use ephemeral or persistent storage paths.

How do other agents access saved query results?

After persistence, Graphify updates its internal store index, enabling agents like reflect (demonstrated in tests/test_reflect.py) to locate results without scanning the filesystem. Agents can also use load_query_result with specific file paths to retrieve individual documents for analysis or enrichment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}