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

> Easily save Graphify query results as memory documents using the API or CLI. Enable downstream agents to retrieve and analyze previous outcomes for powerful data workflows. Learn how now.

- Repository: [Graphify Labs/graphify](https://github.com/Graphify-Labs/graphify)
- Tags: api-reference
- Published: 2026-07-16

---

**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`](https://github.com/Graphify-Labs/graphify/blob/main/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`](https://github.com/Graphify-Labs/graphify/blob/main/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`](https://github.com/Graphify-Labs/graphify/blob/main/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:

```python
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`](https://github.com/Graphify-Labs/graphify/blob/main/.../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:

```bash
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:

```python
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`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/ingest.py)** – Core implementation of `save_query_result` handling validation, payload construction, and file I/O
- **[`tests/test_ingest.py`](https://github.com/Graphify-Labs/graphify/blob/main/tests/test_ingest.py)** – Test suite confirming correct behavior, outcome handling, and edge-case validation
- **[`tests/test_reflect.py`](https://github.com/Graphify-Labs/graphify/blob/main/tests/test_reflect.py)** – Integration examples showing how the `reflect` command consumes saved results
- **[`graphify/cli.py`](https://github.com/Graphify-Labs/graphify/blob/main/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`](https://github.com/Graphify-Labs/graphify/blob/main/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.