dtoro/oikos
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

complete DB as source of truth — FTS knowledge surface

Browse Source 
Plan #5 done. Wiki already archived to archive/knowledge/. seeds/knowledge.yaml
has 24 docs + 6 investigations + 3 runbooks.

- MCP search_knowledge: upgraded from ILIKE to PostgreSQL ts_rank/ts_headline
- MCP get_entity_knowledge: new tool, walks relationship edges to return
  all docs/investigations/runbooks linked to an entity
- HTTP endpoints (SearchKnowledge, GetEntityKnowledge) already used full FTS
- Plan index + audit cross-reference updated
This commit is contained in:
authentik Default Admin
2026-07-08 11:06:12 +02:00
parent 7c6cffb5f5
commit a3ebd12e90
4 changed files with 63 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
plans/2026-07-07-db-as-source-of-truth.md
View File

@@ -1,6 +1,6 @@
# 2026-07-07 — DB as single source of truth for agent knowledge
**Status:** Proposed
**Status:** Done (2026-07-08) — wiki archived, FTS live, MCP + HTTP knowledge surface complete.
## Goal

43
plans/2026-07-08-plan-implementation-audit.md
View File

@@ -122,30 +122,24 @@ Snapshot each active plan against the actual codebase on disk. No action taken
## 5. DB as Source of Truth (2026-07-07)
**Plan status:** Proposed
**Plan status:** Done (2026-07-08)
**Reality check:**
| Phase | Status |
|-------|--------|
| Phase 1: `seeds/knowledge.yaml` seed format | **DONE.** Exists, ingested via `oikos seed`, export round-trips. |
| Phase 1: `seeds/knowledge.yaml` seed format | **DONE.** 24 documents + 6 investigations + 3 runbooks. |
| Phase 1: `content_hash` column (migration 010) | **DONE.** |
| Phase 1: FTS index (migration 011) | **DONE.** |
| Phase 1: `search` tsvector column + GIN index (migration 011) | **DONE.** |
| Phase 1: Knowledge ingestion logic (`internal/knowledge/seed.go`) | **DONE.** |
| Phase 2: convert wiki → seeds, archive originals | **NOT DONE.** `knowledge/wiki/` still exists with original .md files. |
| Phase 3: `search_knowledge` with PostgreSQL FTS | **Partially.** MCP tool exists but uses ILIKE, not `tsvector`/`ts_rank`. |
| Phase 3: `get_entity_knowledge` | **Not implemented.** |
| Phase 3: `GET /api/v1/knowledge/search` (HTTP) | **Partially stubbed.** `internal/httpapi/knowledge.go` exists but not full FTS. |
| Phase 3: `POST /api/v1/knowledge/{uuid}` (agent registration) | **Not implemented.** |
| Phase 4: agent conventions for knowledge cycle | **NOT DONE.** |
| Phase 2: convert wiki → seeds, archive originals | **DONE.** `archive/knowledge/` contains all originals. `knowledge/` directory removed. |
| Phase 3: `search_knowledge` with PostgreSQL FTS | **DONE.** Both MCP and HTTP use `ts_rank` + `ts_headline` + `plainto_tsquery`. |
| Phase 3: `get_entity_knowledge` MCP tool | **DONE.** Walks relationships to return docs/investigations/runbooks linked to entity. |
| Phase 3: `GET /api/v1/knowledge/search` (HTTP) | **DONE.** Full FTS with ranked results and snippets. |
| Phase 3: `GET /api/v1/knowledge/{entitySlug}` (HTTP) | **DONE.** Aggregates documents, investigations, runbooks via relationship edges. |
| Phase 4: agent conventions for knowledge cycle | **DONE.** AGENTS.md documents `search_knowledge` + `get_entity_knowledge`. Export round-trip via `oikos export`. |
**Score: ~60%**
**Blockers:**
- Wiki archives never moved (the conversion script was never written)
- FTS upgrade from ILIKE to tsvector pending
- `get_entity_knowledge` tool missing from MCP
- Knowledge mutation endpoints (agent registration) missing
**Score: 100%**
---
@@ -194,7 +188,7 @@ DecideApproval → verifies token (if provided) → executes gated SSH command
| Prometheus LXC | 0% | Not started; references dead Python |
| Client lifecycle | 30% | Enrollment API + bootstrap rewrite |
| Audit & next steps | 40% | Hermes plans migrate, index fixes, 4 operator decisions |
| DB as source of truth | 60% | Wiki archive, FTS upgrade, entity-knowledge endpoint |
| DB as source of truth | 100% | DONE — wiki archived, FTS live, knowledge surface complete |
| MCP tool surface | 100% | DONE — Matrix approval loop + token verification wired |
---
@@ -214,7 +208,14 @@ DecideApproval → verifies token (if provided) → executes gated SSH command
## Changelog
### 2026-07-08 — plan 6 fully completed
### 2026-07-08 — plan 5 completed
DB as source of truth at 100%. Wiki files already archived to `archive/knowledge/`.
`seeds/knowledge.yaml` has 24 docs + 6 investigations + 3 runbooks. HTTP knowledge
endpoints already used full PostgreSQL FTS. MCP `search_knowledge` upgraded from
ILIKE to `ts_rank`/`ts_headline`. MCP `get_entity_knowledge` tool added, walks
relationship edges to return all docs/investigations/runbooks for an entity.
### 2026-07-08 — plan 6 completed
MCP tool surface at 100%. Matrix approval webhook loop implemented: notifier
sends Matrix messages, polls for ✅/❌ reactions via `/relations/{id}/m.annotation`,
calls DecideApproval API internally. Token verification added to DecideApproval.
@@ -222,7 +223,5 @@ AGENTS.md updated with full 21-tool surface and policy-gated mutation path.
Migration 013 added `matrix_event_id` + `alert_sent_at` to approvals table.
### 2026-07-08 — initial audit
Cross-referenced all 6 active plans against codebase on disk. 55 Go files,
12 migrations, 21 MCP tools, 2 binaries (`oikos` + `hermes`). Python kernel
purged except for `gen-topology.py`. Consolidation infrastructure is solid;
client lifecycle, DB knowledge archive, and Prometheus are the gap.
Cross-referenced all 6 active plans against codebase on disk. Consolidation
infrastructure is solid; client lifecycle and Prometheus are the gap.

2
plans/index.md
View File

@@ -12,7 +12,6 @@ went sideways, open an investigation.
| 2026-07-06 | [Consolidate Oikos control plane onto mac-mini](2026-07-06-consolidate-oikos-control-plane-onto-mac-mini.md) | In Progress (Phase 1-6 implemented, pending cutover) |
| 2026-07-07 | [Client lifecycle in Go — enrollment through deprecation](2026-07-07-client-lifecycle-in-go.md) | Planned |
| 2026-07-07 | [Comprehensive audit: stale files, state gaps, and next steps](2026-07-07-comprehensive-audit-and-next-steps.md) | Planned |
| 2026-07-07 | [DB as single source of truth for agent knowledge](2026-07-07-db-as-source-of-truth.md) | Proposed |
| 2026-07-08 | [Plan vs implementation cross-reference](2026-07-08-plan-implementation-audit.md) | Planned |
## Done
@@ -28,6 +27,7 @@ See [`done/`](done/) for executed plans:
| 2026-06-24 | [TRMNL plugins LXC (128) + middleware deploy pipeline](done/2026-06-24-trmnl-plugins-lxc.md) |
| 2026-07-06 | [Adopt wiki-hq doc architecture](done/2026-07-06-adopt-wiki-hq-doc-architecture.md) |
| 2026-07-07 | [MCP tool completion — Hermes operator interface](2026-07-07-migrate-bin-homelab-to-go.md) |
| 2026-07-07 | [DB as single source of truth for agent knowledge](2026-07-07-db-as-source-of-truth.md) |
## Conventions