Operating a Self-Hosted Agent Knowledge Base: Backup, Upgrades, and Maintenance
Practical operational guide for self-hosting an agent knowledge base: managing Git versioning, index synchronization, dual-state backup and restore, upgrade ownership, and MCP client stability.
A self-hosted knowledge base needs an operating plan as well as an installation plan. For platform teams preparing to connect agents, the central question is whether data, permissions, and retrieval can be recovered together after a failure or upgrade. This guide proposes checks to run on your deployment; it does not report completed AKB acceptance tests or promise recovery times.
Key takeaways
- Inventory the whole installation, including data, files, configuration, and recovery credentials.
- Choose a backup method against your recovery objectives; WAL archiving is not the only option.
- Prove recovery with representative reads, writes, files, search, and permission tests.
- Rehearse migrations and recovery before upgrading production.
- Assign owners and keep evidence for maintenance checks.
Define the recovery boundary
AKB’s documented architecture combines Git document history, PostgreSQL data and metadata, and a configurable vector index. A Git repository copy is not a backup of the entire installation. The exact state to protect depends on the release, storage driver, authentication setup, and optional integrations in use.
Build a deployment-specific inventory covering document revisions, database data and authorization state, original files and attachments, application/database configuration, protected recovery keys, search indexes and embedding configuration, external audit retention, and optional connector or curation checkpoints. Confirm actual storage locations and supported recovery procedures. Distinguish source data from indexes that can be rebuilt; include rebuild time in recovery planning.
For each item assign an owner, backup schedule, retention policy, access restrictions, and restore procedure. Keep protected copies outside the primary failure domain where appropriate. Do not place secret values in the runbook.
Define recovery point objective (RPO), the acceptable data-loss interval, and recovery time objective (RTO), the allowed time to validated service restoration. Set targets from workload needs and measure them in drills; they are not AKB defaults or SLAs.
Select and test a backup strategy
PostgreSQL documents SQL dumps, filesystem-level backups, and continuous archiving as distinct approaches. Select a supported method using documentation for the deployed major version. Point-in-time recovery needs a suitable base backup and an unbroken WAL sequence through the recovery target; WAL files alone are insufficient, and a logical dump is not a base for WAL replay. See Backup and Restore and Continuous Archiving.
Where WAL archiving is used, prevent replacement of an archive with different contents. A previously archived identical file may be acknowledged as successful only when it is fully persisted. Monitor archival failures and storage pressure. Use a tested archive implementation rather than a short copy script.
Database recovery does not recover manual configuration changes outside the database. Protect those files separately. Coordinate database, document, and attachment recovery points using the deployment’s supported consistency procedure, such as quiescing writes where required. Independently timed copies can restore references to missing or mismatched content.
Rehearse restoration before an incident
Run these proposed checks in an isolated recovery environment:
- Identify the intended recovery point, exact backup set, application/database versions, storage driver, and required configuration.
- Restore coherent data, files, and necessary configuration or keys. Prevent test environments from issuing production jobs or outbound writes.
- Check a known document revision, representative table row, and file checksum against the recovery manifest. Verify important references.
- Rebuild derived state using the supported procedure where necessary. Check retrieval and indexing status rather than equating startup with search readiness.
- Reconcile permission changes and credential revocations made after the backup. Test allowed and denied identities through every deployed interface, including UI, API, or MCP as applicable.
- Measure the recovered data boundary and total restoration time, including rebuild and validation. Record observed RPO/RTO, errors, and untested paths.
- Reopen approved access after the designated owner accepts the evidence. Avoid blanket authentication or network-access relaxation.
Restoring an older database may restore older access state. A successful content check therefore does not establish that reconnecting current users or agents is safe.
Plan upgrades around data compatibility
Record backend, frontend, client/proxy, database, storage driver, and model configuration. Review release-specific migration requirements and supported version combinations, then rehearse against a representative restored environment.
Before production changes, verify the recovery backup and define stop/go criteria, ownership, maintenance access, and recovery path. Test authorized retrieval and writing, denied access, files, and search after the change. Confirm how pending jobs and writes are handled during restart.
An application image rollback does not undo an incompatible schema or data migration. Use a tested release-specific rollback or restore procedure and account for writes accepted after the pre-upgrade backup. Do not assume rolling upgrades or zero downtime without evidence for the actual topology.
Validate the selected MCP client/server/proxy and protocol version together. AKB client documentation describes connection options. Test deployed authentication, transport, and tools rather than relying on a generic handshake. Core service, client integrations, and optional collection or curation services may require separate upgrade owners.
Make maintenance observable
- Platform/database operator: track backup age, failures, retention, and the latest restore drill.
- Storage operator: monitor capacity, WAL growth, archival failures, and alert response.
- Retrieval operator: measure update-to-search visibility, backlog age, and degraded behavior.
- Service owner: retain request counts, errors, timeout policy, and incident actions.
- Application owner: test stale-revision conflicts and retry reconciliation.
- Identity/platform owner: review expiry, rotation, and access outcomes without recording secret values.
- Release owner: retain version manifests, migration rehearsals, and recovery evidence.
WAL archive overwrite protection is not an application-level concurrency mechanism. Test conflicting edits and lost responses using the supported write contract; reconcile stored state before retrying an uncertain operation. Do not assume automatic merging or exactly-once writes.
Document revision history differs from access auditing. Verify capture coverage and retention for each interface used; AKB audit documentation describes an optional capability, not a universal completeness guarantee.
Licensing and deployment scope
Review the applicable release’s AKB LICENSE. Its BSL 1.1 production grant uses fewer than 100 aggregated Named Seats under its definitions; production use at or above that threshold, or third-party hosted, embedded, or rebranded service offerings at any seat count, requires a commercial license. The separate proxy license does not remove backend obligations. Confirm terms for the intended deployment.
FAQ
Is a Git copy enough to recover AKB?
No. Inventory database, files, configuration, keys, and other deployed state as well as document history. Determine which indexes can be rebuilt and include rebuild time in the test.
What proves a restore worked?
A recorded drill validating expected content, representative files and tables, usable retrieval, and current access restrictions. A healthy process or completed restore command alone is insufficient.
Can we recover from an upgrade by reverting an image?
Only if that path is compatible with the resulting data and schema and has been tested. Otherwise use the documented recovery plan and account for intervening writes.
Explore Dnotitia’s Agent Knowledge Infrastructure
Discover how AKB provides reliable, versioned memory and hybrid retrieval for autonomous AI agents across self-hosted environments.
