Dynamic Knowledge Spaces: Keep AI Context Current, Structured, and Traceable

The knowledge freshness problem

Most AI knowledge-base systems have a hidden weakness.

They work well in the first demo:

Upload documents
        ↓
Ask a question
        ↓
Get an answer

But real business information changes constantly.

• A supplier sends a corrected invoice.
• A contract is amended.
• A price list is updated.
• A new version of an operational policy is published.
• A customer uploads a replacement document.
• A spreadsheet export is corrected.
• A voice note is replaced with a clearer recording.
• A document is assigned to the wrong project or customer.
• A previously relevant file should no longer influence cross-document answers.

If the old content remains active in a knowledge base, the agent may retrieve outdated information.

Old contract value
+ new invoice value
+ outdated price list
        ↓
Agent receives conflicting context
        ↓
Agent gives a plausible but incorrect answer

This is not only a retrieval problem.

It is a data-governance problem.

A Knowledge Space must be able to answer:

Which sources are currently active?

Which document is the authoritative source?

Which version of this document should an agent use?

When was this source last updated?

Was an outdated document removed from cross-document reasoning?

Did a replacement preserve the document identity used by existing workflows?

Production RAG and AI-agent systems need freshness, versioning, lineage, and deprecation controls. When multiple active versions of the same source remain available, retrieval can select a stale version even when the retrieval model itself behaves correctly.

Claix now gives developers direct API controls for managing this lifecycle.

What changes with dynamic Knowledge Spaces?

Previously, a document's relationship with a Knowledge Space was primarily decided during extraction.

Process a document with space_id
        ↓
Document becomes part of the Knowledge Space
        ↓
Query the Knowledge Space later

That is still the fastest approach when you already know where a source belongs.

But business workflows are not always predictable.

Sometimes a document is processed first and categorized later. Sometimes a document needs to move between contexts. Sometimes the original file is corrected. Sometimes the same business record must retain a stable identifier while its underlying content changes.

Claix now supports three operations for that reality:

These calls are free. They do not consume extraction credits or Context Window credits.

The result is a Knowledge Space that behaves less like a static upload folder and more like a maintained source-of-truth layer for applications, workflows, and AI agents.

Add an existing document to a Knowledge Space

Process first, organize later

A common workflow looks like this:

Customer uploads a PDF
        ↓
Your application processes it with Claix
        ↓
Claix returns structured data and a document_id
        ↓
Your workflow determines which supplier, project, case, or account it belongs to
        ↓
Add the existing document to the correct Knowledge Space

This is useful when classification happens after extraction.

For example:

• A backend receives documents before it knows the relevant customer account.
• An automation receives files from email and classifies them later.
• A workflow extracts supplier information first, then assigns the source to a supplier Knowledge Space.
• A human reviewer decides which project a document belongs to.
• An agent identifies the appropriate case, vendor, or customer context after reading the extracted result.

Use:

POST https://claix.dev/add-space

With:

{
  "document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
  "space_id": "5b9e2c14-7d3a-4f8b-9e1c-6a0d4b8f2e7c"
}

A successful response confirms that the document is now part of the Knowledge Space:

{
  "success": true,
  "document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
  "space_id": "5b9e2c14-7d3a-4f8b-9e1c-6a0d4b8f2e7c",
  "space_name": "Suppliers 2026",
  "file_name": "invoice.pdf",
  "version": 1,
  "message": "Document added to Knowledge Space."
}

From that point, the document participates in cross-document queries for that space.

Why post-processing assignment matters

Many document platforms assume that categorization happens before or during ingestion.

That is not always how real systems work.

Consider a multi-tenant SaaS application:

New document arrives
        ↓
No user has assigned it to a project yet
        ↓
Claix extracts supplier, customer, contract number, and reference data
        ↓
Your business logic identifies the correct account
        ↓
The document is added to the corresponding Knowledge Space

The same pattern works for:

Document received
        ↓
Extract data
        ↓
Classify based on result
        ↓
Assign to space

This is more flexible than forcing every source to have a fixed destination before the system understands what the source contains.

A document can be extracted once, persist its context, and later be organized into the Knowledge Space where it becomes useful.

Remove a document from a Knowledge Space

Remove context without deleting the document

A document does not need to be permanently deleted just because it should no longer affect cross-document reasoning.

For example:

• A document was attached to the wrong supplier.
• A contract no longer belongs to the active project space.
• A duplicate invoice should not affect supplier totals.
• A customer file must be moved out of a case-specific context.
• A document needs review before it is reclassified.
• A workflow should stop using a source for cross-document answers while retaining it for audit or direct queries.

Claix now supports removing a document from its current Knowledge Space while keeping the persisted document available.

Use:

DELETE https://claix.dev/remove-document-from-space/{document_id}

The endpoint also accepts POST for clients that cannot send DELETE requests.

Example:

DELETE https://claix.dev/remove-document-from-space/d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b

After a successful response:

{
  "success": true,
  "document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
  "previous_space_id": "5b9e2c14-7d3a-4f8b-9e1c-6a0d4b8f2e7c",
  "space_id": null,
  "file_name": "invoice.pdf",
  "version": 1,
  "message": "Document removed from Knowledge Space. It no longer has a space_id."
}

• The document still exists.
• Its document_id still works.
• Its persisted context remains available.
• You can still query it directly through document context.

What changes is only this:

The document no longer participates in Knowledge Space queries.

Why removal is safer than deletion

A destructive delete operation is not the correct answer for every knowledge-management change.

There is a major difference between:

Delete the source permanently

and:

Remove the source from this group of related documents

With Claix:

Removing a document from a Knowledge Space is therefore useful for safe reclassification.

Remove from current space
        ↓
Review or classify document
        ↓
Optionally add it to another space

This avoids stale context and accidental duplicate reasoning while preserving the original source for investigation, compliance, or later reuse.

Replace a document without changing its document_id

Keep stable identity while updating content

The most important new operation is document replacement.

A document may be referenced by:

• An application database.
• A CRM record.
• A customer case.
• An approval workflow.
• An AI agent task.
• An MCP client.
• An A2A task.
• A support ticket.
• A Knowledge Space.
• A log entry.
• A business rule.
• A human-review queue.

If the document is updated, forcing every downstream system to adopt a new document_id creates unnecessary complexity.

Claix now supports replacing a persisted document's content while preserving the stable document_id.

Use:

POST https://claix.dev/replace-document

Request body:

{
  "document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
  "new_content_document_id": "a8c3f1e0-2d4b-4a9e-8c71-5f0e2b9d6a3c"
}

The flow is designed for a simple replacement pattern:

1. Process the new source normally.
2. Receive a temporary new_content_document_id.
3. Replace the stable document content.
4. Continue using the original document_id everywhere.

The source document contributes its processed content and file name to the stable document. After the replacement succeeds, the source document is deleted.

Existing stable document
document_id: doc_A
        ↓
Newly processed replacement source
document_id: doc_B
        ↓
Claix replaces doc_A content with doc_B content
        ↓
doc_A remains the stable document_id
doc_B is removed

The Knowledge Space membership of doc_A remains intact.

Why stable document IDs matter

Stable identifiers are important whenever another system stores references.

Imagine a supplier Knowledge Space containing:

Supplier contract
Purchase order
Invoice
Price list

Your workflow may already use:

document_id = supplier-invoice-record

for:

• Direct document queries.
• Cross-document reconciliation.
• Finance approval workflows.
• Audit logs.
• Source citations.
• Customer-facing status pages.
• Internal references.
• Agent task state.

Now the supplier sends a corrected invoice.

Without replacement support, you would have to:

Process corrected invoice
        ↓
Receive a new document_id
        ↓
Remove old document from Knowledge Space
        ↓
Add new document to Knowledge Space
        ↓
Update every stored reference
        ↓
Update every workflow
        ↓
Ensure old source no longer influences query results

With Claix document replacement:

Process corrected invoice
        ↓
Receive temporary document ID
        ↓
Replace existing stable document content
        ↓
Continue using the original document_id

• The workflow can keep its references intact.
• The Knowledge Space can keep its membership intact.
• The document context remains addressable through the same identifier.

This is a much better model for systems where documents are part of an ongoing business process rather than one-time uploads.

What document replacement preserves

When you replace a Claix document, the destination document keeps its stable identity.

Kept:
- document_id
- Knowledge Space membership
- downstream references
- application-level relationships
- existing business identity

The replacement updates the source content that Claix uses for context and reasoning.

Updated:
- file name
- processed content
- extracted structured data
- document context used for reasoning
- source evidence
- document metadata derived from the replacement source
- active document version

The response includes a new version number:

{
  "success": true,
  "swap_id": "c1e7a4b2-9f0d-4e8a-b3c5-1d2e3f4a5b6c",
  "document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
  "source_document_id": "a8c3f1e0-2d4b-4a9e-8c71-5f0e2b9d6a3c",
  "file_name": "corrected-invoice.pdf",
  "version": 2,
  "swaps_count": 1,
  "message": "Content replaced. The source document was deleted."
}

• The swap_id gives the replacement operation a traceable identifier.
• The version tells downstream systems that the content behind the stable document_id has changed.
• The swaps_count makes it possible to understand how many times the stable document has been updated.

Dynamic Knowledge Spaces prevent stale agent context

Static knowledge is an operational risk

A static Knowledge Space accumulates problems over time:

Original invoice
+ corrected invoice
+ outdated contract
+ duplicate spreadsheet
+ old price list
        ↓
Conflicting context
        ↓
Unreliable retrieval
        ↓
Incorrect agent answer

If an AI agent sees both the old and corrected invoice, it may:

• Use the wrong amount.
• Add both values.
• Cite the superseded source.
• Treat old terms as current.
• Identify a false discrepancy.
• Give a correct answer for the wrong version of reality.

This is why dynamic Knowledge Space management matters.

The goal is not merely to let users move files around.

The goal is to maintain a current and authoritative set of sources for agent reasoning.

Relevant source enters the space
        ↓
Outdated source leaves the space
        ↓
Corrected source replaces old content
        ↓
Queries use the current source of truth

Knowledge-base reliability depends heavily on freshness, source lineage, active versus deprecated content, and removal of stale versions from retrieval. Multiple active versions of the same business record can cause agents to retrieve outdated or contradictory information.

Example: supplier invoice reconciliation

A procurement workflow processes:

supplier-contract.pdf
purchase-order.pdf
invoice-march.pdf
price-list.xlsx

All sources belong to:

Knowledge Space: Supplier A — 2026

An agent asks:

Does the March invoice match the agreed contract price?

Initially, the answer uses:

supplier-contract.pdf
+ purchase-order.pdf
+ invoice-march.pdf
+ price-list.xlsx

Later, the supplier issues a corrected invoice.

A static knowledge-base workflow would create a second invoice record:

invoice-march.pdf
invoice-march-corrected.pdf

Now the Knowledge Space contains two versions of the same business record.

A dynamic Claix workflow does this instead:

1. Process invoice-march-corrected.pdf.
2. Receive temporary source document ID.
3. Call POST /replace-document.
4. Preserve the original invoice document_id.
5. Increment the document version.
6. Delete the temporary source document.
7. Keep the same Knowledge Space membership.

The agent now sees one active March invoice record with updated content.

That reduces duplicate context and preserves the stable business relationship between the invoice and the rest of the supplier space.

Example: customer case management

A customer-support application maintains one Knowledge Space per case:

Case 4382
        ↓
Customer emails
Support screenshots
Voice notes
Contracts
Invoices
Internal reports

A support agent may ask:

What has the customer already been told about the refund?

What invoice is being disputed?

Was a delivery date promised?

Which documents support the customer's claim?

Over time:

• A screenshot is uploaded to the wrong case.
• A voice note needs to be reclassified.
• A customer submits a corrected form.
• An internal support summary is replaced with a final version.

Dynamic Knowledge Spaces allow the application to manage that context without deleting everything and rebuilding the case from scratch.

Wrong screenshot
        ↓
Remove from Knowledge Space

Corrected form
        ↓
Process replacement
        ↓
Replace original document content

New support attachment
        ↓
Process
        ↓
Add to Knowledge Space

The Knowledge Space remains current and useful to agents throughout the case lifecycle.

Dynamic context for applications, workflows, and agents

Knowledge Spaces are useful for AI agents, but they are not only for agents.

They can support any system that needs current, cross-source context.

Backend applications

A backend can maintain a stable document reference:

document_id

while allowing the source content to be updated.

For example:

Customer record
        ↓
document_id stored in database
        ↓
Customer uploads corrected source
        ↓
Claix replacement call
        ↓
Existing database reference remains valid

The backend does not need to update foreign keys or rewire relationships across the application.

Automation workflows

n8n, Make, Zapier, and custom automation workflows often need to react to changing business inputs.

A workflow can:

Process new source
        ↓
Check whether it replaces an existing record
        ↓
Call replace-document
        ↓
Query the updated Knowledge Space
        ↓
Continue with current data

Or:

Classify processed source
        ↓
Add it to a Knowledge Space
        ↓
Ask cross-document questions
        ↓
Route discrepancies to review

AI agents

An agent can work with a Knowledge Space that reflects the current operating state rather than a historical pile of files.

Agent asks:
"What is the current contract price?"

Knowledge Space:
Contains only current active source content

Agent receives:
Answer grounded in current documents

That is critical for agent workflows involving:

• Payments.
• Procurement.
• Contracts.
• Customer support.
• Compliance.
• Operations.
• Supplier management.
• Onboarding.
• Due diligence.
• Case management.
• Finance reconciliation.

Document replacement and traceability

Dynamic does not mean untraceable.

A common concern with replacing content is:

If the document changes, how do we know what happened?

Claix returns a swap_id for each replacement operation:

{
  "swap_id": "c1e7a4b2-9f0d-4e8a-b3c5-1d2e3f4a5b6c"
}

This identifies the content-replacement event.

The response also includes:

document_id
source_document_id
version
swaps_count
file_name

That gives applications operational traceability:

Stable document identity:
document_id

Replacement source:
source_document_id

Replacement operation:
swap_id

Current content version:
version

Total number of replacements:
swaps_count

The document's version increases after each replacement.

Version 1
        ↓
Corrected source processed
        ↓
Version 2
        ↓
Updated source processed again
        ↓
Version 3

This lets a workflow know that the content behind a stable document ID has changed.

A reliable system should record that change alongside its own business events:

{
  "workflow_run_id": "supplier-reconciliation-2026-09-25-0081",
  "document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
  "document_version": 2,
  "claix_swap_id": "c1e7a4b2-9f0d-4e8a-b3c5-1d2e3f4a5b6c",
  "action": "reconcile_corrected_invoice"
}

This is especially useful when an agent or automation makes decisions based on changing sources.

Source tracing after a replacement

Claix source tracing provides evidence for extracted fields and query answers.

For a PDF, source evidence can refer to:

• Page
• Paragraph
• Clause
• Table
• Text fragment

For a spreadsheet:

• Column
• Row
• Source cell

For audio:

• Second
• Time range
• Spoken fragment

After replacement, the stable document_id remains the same, but the active content and its source evidence are updated to the replacement source.

This matters because a source citation must refer to the content currently available to the workflow.

Before replacement:
document_id → old PDF page 2

After replacement:
same document_id → corrected PDF page 2

Applications that need audit-grade history should store:

document_id
document version
swap_id
log_id
source evidence
workflow decision
timestamp

For standard operational workflows, using the latest active source evidence is usually sufficient.

For high-impact workflows—payments, legal approvals, access decisions, regulatory processes, or financial reconciliation—recording the document version and swap_id alongside the decision creates a stronger audit trail.

A better model than re-uploading everything

Without dynamic Knowledge Spaces, many teams use inefficient workarounds.

Workaround 1: recreate the entire Knowledge Space

Delete old Knowledge Space
        ↓
Reprocess every source
        ↓
Create a new Knowledge Space
        ↓
Update all references
        ↓
Hope nothing still points to the old space

This creates unnecessary work, duplicated processing, and reference-management problems.

Workaround 2: keep every version active

Original document
+ corrected document
+ updated document
+ final document
        ↓
Knowledge Space grows
        ↓
Agent sees multiple conflicting versions

This increases the risk of stale or contradictory answers.

Workaround 3: delete the old document and create a new one

Old document_id deleted
        ↓
New document_id created
        ↓
Application references break
        ↓
Workflows need updates
        ↓
Context relationships must be rebuilt

Claix document replacement avoids these issues:

Process new source
        ↓
Replace existing stable document content
        ↓
Keep the same document_id
        ↓
Keep the same Knowledge Space membership
        ↓
Use the current version in future queries

This is a simpler model for APIs, developers, automation tools, and AI systems.

When to add, remove, or replace

Use the following decision guide.

How to add a document to a Knowledge Space

Endpoint

POST https://claix.dev/add-space

Request

{
  "document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
  "space_id": "5b9e2c14-7d3a-4f8b-9e1c-6a0d4b8f2e7c"
}

cURL example

curl -X POST "https://claix.dev/add-space" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_CLAIX_API_KEY" \
  -d '{
    "document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
    "space_id": "5b9e2c14-7d3a-4f8b-9e1c-6a0d4b8f2e7c"
  }'

The document and Knowledge Space must belong to the same Claix account.

A document can only have one active space_id. If it already belongs to a space, remove it first.

How to remove a document from a Knowledge Space

Endpoint

DELETE https://claix.dev/remove-document-from-space/{document_id}

cURL example

curl -X DELETE \
  "https://claix.dev/remove-document-from-space/d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b" \
  -H "x-api-key: YOUR_CLAIX_API_KEY"

This operation:

• Keeps the document persisted
• Keeps the document_id valid
• Keeps direct document context available
• Removes the document from Knowledge Space queries
• Sets space_id to null

It does not delete the source file or its context.

How to replace document content

Endpoint

POST https://claix.dev/replace-document

Request

{
  "document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
  "new_content_document_id": "a8c3f1e0-2d4b-4a9e-8c71-5f0e2b9d6a3c"
}

cURL example

curl -X POST "https://claix.dev/replace-document" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_CLAIX_API_KEY" \
  -d '{
    "document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
    "new_content_document_id": "a8c3f1e0-2d4b-4a9e-8c71-5f0e2b9d6a3c"
  }'

Expected result

{
  "success": true,
  "swap_id": "c1e7a4b2-9f0d-4e8a-b3c5-1d2e3f4a5b6c",
  "document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
  "source_document_id": "a8c3f1e0-2d4b-4a9e-8c71-5f0e2b9d6a3c",
  "file_name": "corrected-invoice.pdf",
  "version": 2,
  "swaps_count": 1,
  "message": "Content replaced. The source document was deleted."
}

After replacement:

Continue querying:
document_id = d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b

Do not continue using:

new_content_document_id = a8c3f1e0-2d4b-4a9e-8c71-5f0e2b9d6a3c

The replacement source is deleted after a successful swap.

Security and ownership controls

All Knowledge Space management endpoints require a Claix API key.

Use one of:

x-api-key: YOUR_CLAIX_API_KEY

or:

Authorization: Bearer YOUR_CLAIX_API_KEY

Claix verifies:

• The API key exists and is active.
• The account is active.
• The document belongs to the API-key account.
• The Knowledge Space belongs to the API-key account.
• A replacement source belongs to the same account.

Invalid or cross-account document references cannot be used to manipulate another account's context.

Never expose a Claix API key in browser-side code, public repositories, client applications, screenshots, or logs.

Use Claix from a backend, secure serverless function, integration platform credential store, or trusted automation environment.

Dynamic Knowledge Spaces and AI reliability

The value of a Knowledge Space is not only the ability to query many documents together.

The value is the ability to query the right current documents together.

An agent can only produce reliable cross-document answers if:

The relevant sources are included
        +
The irrelevant sources are excluded
        +
Corrected sources replace superseded ones
        +
Document identity remains stable where workflows depend on it
        +
Changes are traceable

Dynamic Knowledge Spaces make this possible.

They give applications and agents a practical lifecycle for context:

Ingest
        ↓
Extract
        ↓
Assign
        ↓
Query
        ↓
Remove
        ↓
Replace
        ↓
Query current context again

This is more useful than treating a Knowledge Space as a static RAG bucket.

It turns it into a maintained context layer for live business operations.

Final takeaway

AI agents, retrieval systems, backend applications, and automation workflows should not reason over static collections of files forever.

• Business context changes.
• Invoices are corrected.
• Contracts are amended.
• Documents are misclassified.
• Audio recordings are replaced.
• New information arrives.
• Old information stops being relevant.

Claix Knowledge Spaces now support that reality.

Add the sources that matter. Remove the sources that no longer belong. Replace outdated content without breaking document identity. Keep the context your AI systems use current, structured, and traceable.

Claix gives developers a dynamic Knowledge Space API for managing document context across PDFs, spreadsheets, images, text, HTML, XML, and audio—so applications, workflows, and AI agents can reason over current business information instead of stale uploads.