Knowledge Base Maintenance

A RAG index goes stale when source content changes. The SDK gives you two maintenance paths:

Need	SDK method
Rebuild a source and upsert the new chunks	`rag.ingest(...)` or manual stages ending in `rag.store(...)`
Replace known chunk IDs	`rag.edit(chunks=[...])`
Remove stale chunk IDs	`rag.delete(ids=[...])`

Track Source Manifests

For long-lived indexes, keep a manifest that maps each source to the chunk IDs produced from it.

manifest = {
    "policy.md": {
        "chunk_ids": ["policy-0", "policy-1"],
        "checksum": "...",
    }
}

When the source changes, re-ingest it, compare old IDs to new IDs, and delete stale chunks.

old_ids = set(manifest.get("policy.md", {}).get("chunk_ids", []))

result = rag.ingest(markdown=[{"text": updated_policy, "source": "policy.md"}])
new_ids = {item["id"] for item in result.store_result.items}

stale_ids = old_ids - new_ids
if stale_ids:
    rag.delete(ids=sorted(stale_ids))

manifest["policy.md"] = {"chunk_ids": sorted(new_ids)}

Edit Known Chunks

Use edit() when you know the exact chunk IDs to replace.

edited = rag.edit(chunks=[
    {
        "id": "refund-policy-0",
        "text": "Customers can request a refund within 45 days of purchase.",
        "source": "policy.md",
        "metadata": {"title": "Refund policy"},
    }
])

edited.requested
edited.edited
edited.failed
edited.errors

edit() re-embeds the replacement chunk text before writing it back to the vector database.

Delete Removed Chunks

Use delete() for exact chunk IDs that should no longer appear in retrieval.

deleted = rag.delete(ids=["refund-policy-0", "refund-policy-1"])

deleted.requested
deleted.deleted
deleted.failed
deleted.errors

Deletes do not perform semantic matching. They only remove exact IDs.

Full Refresh Pattern

def refresh_source(source_id: str, text: str, manifest: dict) -> None:
    old_ids = set(manifest.get(source_id, {}).get("chunk_ids", []))
    result = rag.ingest(markdown=[{"text": text, "source": source_id}])
    new_ids = {item["id"] for item in result.store_result.items}

    stale = old_ids - new_ids
    if stale:
        rag.delete(ids=sorted(stale))

    manifest[source_id] = {"chunk_ids": sorted(new_ids)}

Operational Guidance

Concern	SDK practice
Stable IDs	Preserve `source` metadata and use deterministic source inputs so chunk IDs stay traceable.
Partial failures	Check `failed` and `errors` on every result before updating your manifest.
Deletes	Delete old IDs only after the replacement ingest succeeds.
Auditing	Store source ID, checksum, chunk IDs, and update time outside Ragrails.
Drift	Re-query after updates to verify the expected chunks are retrieved.

Storing

Use store, edit, and delete directly.

Retrieval

Verify updated results.

Get Started

Workflows

Pipeline

Maintenance

Knowledge Base Maintenance

Track Source Manifests

Edit Known Chunks

Delete Removed Chunks

Full Refresh Pattern

Operational Guidance

Storing

Retrieval

​Track Source Manifests

​Edit Known Chunks

​Delete Removed Chunks

​Full Refresh Pattern

​Operational Guidance

Storing

Retrieval

Track Source Manifests

Edit Known Chunks

Delete Removed Chunks

Full Refresh Pattern

Operational Guidance