208 lines
8.5 KiB
Markdown
208 lines
8.5 KiB
Markdown
---
|
|
name: teleo-kb-bridge
|
|
description: Use the GCP Cloud SQL KB bridge before answering questions about claims, evidence, edges, schema-backed soul/context, KB approval, or KB edit workflow.
|
|
version: 1.0.0
|
|
author: m3taversal
|
|
license: MIT
|
|
metadata:
|
|
hermes:
|
|
tags: [teleo, kb, postgres, cloudsql, claims, evidence, governance]
|
|
related_skills: [leo-synthesis-methods]
|
|
---
|
|
|
|
# Teleo KB Bridge
|
|
|
|
The canonical Teleo knowledge base is Postgres, not runtime memory.
|
|
|
|
This is the GCP parallel leoclean surface. The local bridge command is still the
|
|
only path Leo should use directly:
|
|
|
|
```bash
|
|
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb context "<question>"
|
|
```
|
|
|
|
On GCP, `teleo-kb` routes to the Cloud SQL wrapper. Do not use raw
|
|
container-Postgres commands from the VPS playbook; those are not valid on the
|
|
GCP VM.
|
|
|
|
Use narrower bridge commands when needed:
|
|
|
|
```bash
|
|
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb status
|
|
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb search "<terms>"
|
|
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb context "<question>"
|
|
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb show <claim_id>
|
|
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb evidence <claim_id>
|
|
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb edges <claim_id>
|
|
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb list-proposals
|
|
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb search-proposals "<terms>"
|
|
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb show-proposal <proposal_id>
|
|
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb decision-matrix-status
|
|
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb propose-core-change --proposal-type revise_claim --target-kind claim --target-ref "<claim id or description>" --proposed "<replacement>" --source-ref "<telegram/chat/source ref>" --rationale "<why this should be reviewed>"
|
|
```
|
|
|
|
## Answer Discipline
|
|
|
|
For non-live questions, answer from the Cloud SQL KB after a bounded read. A
|
|
good default is:
|
|
|
|
1. `teleo-kb context "<question>"`;
|
|
2. at most three `show` / `evidence` / `edges` follow-ups for the most relevant
|
|
IDs;
|
|
3. final answer with what is grounded, what is weak, and what evidence would
|
|
improve it.
|
|
|
|
For no-context direct claims such as "Is X in Leo now?", "did the DB change?",
|
|
"did the decision matrix approve this?", or "is it still just proposals?", do
|
|
not stop at `search` or default `list-proposals`. Run the status-specific
|
|
proposal and governance readbacks needed to avoid overclaiming:
|
|
|
|
```bash
|
|
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb search-proposals "<entity/framework/claim terms>" --status all --limit 20
|
|
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb decision-matrix-status
|
|
```
|
|
|
|
If `decision-matrix-status` says the matrix tables are absent or incomplete,
|
|
do not infer matrix approval from proposal rationale, reviewer notes, or
|
|
`kb_stage.kb_proposals.status`. Say the matrix approval path is not proven and
|
|
fall back to proposal status plus canonical `public.*` readback.
|
|
|
|
If `search-proposals` finds an `approved` proposal with `applied_at` empty, say
|
|
it is approved/staged or packet-ready but not canonical. Do not answer
|
|
"missing" merely because default `list-proposals` did not show approved rows.
|
|
|
|
## Telegram Rendering
|
|
|
|
Make KB answers easy to scan in Telegram:
|
|
|
|
- wrap claim IDs, proposal IDs, edge types, table names, statuses, counts, and
|
|
command names in backticks;
|
|
- when citing a specific claim, include both the claim headline and the claim
|
|
ID, for example: `claim text` (`<claim_id>`);
|
|
- when the bridge output includes `claim page: https://leo.livingip.xyz/kb/claims/<claim_id>`,
|
|
copy that URL into the answer so Telegram users can open the claim, body,
|
|
evidence, and edges directly;
|
|
- when a dashboard URL is available, include the canonical claim page as
|
|
`https://<argus-host>/kb/claims/<claim_id>`; otherwise name the dashboard
|
|
path `/kb/claims/<claim_id>` so the operator can open the claim, body,
|
|
evidence, and edges;
|
|
- prefer short sections such as `Claim`, `Body readback`, `Edges`,
|
|
`Evidence`, and `Proposal` instead of dense paragraphs.
|
|
|
|
Do not browse the public web just because the KB has evidence gaps. If the user
|
|
asks for current Twitter/X, current market activity, today's news, or another
|
|
fresh external read, use the configured current-source path if it exists. If it
|
|
does not exist, say the fresh external source is unavailable from this runtime
|
|
and answer from cached/canonical context with an explicit freshness caveat.
|
|
|
|
## When To Use This
|
|
|
|
Use this bridge before answering when the user asks:
|
|
|
|
- what the KB says;
|
|
- whether a claim is approved, grounded, contradicted, or superseded;
|
|
- what evidence supports a claim;
|
|
- which claims support/challenge/relate to another claim;
|
|
- how to approve/edit/retire/supersede a claim;
|
|
- what the schema-backed soul/context says about roles, peers, blindspots, strategy, rules, or reasoning tools.
|
|
|
|
## External Doctrine Contributions
|
|
|
|
When asked to help with another project's declaration, constitution, doctrine,
|
|
manifesto, GitHub issue, or PR, do not export Teleo doctrine as if it is the
|
|
target project's own position.
|
|
|
|
Use the target project's native language first. If the external text says
|
|
phrases like `no single voice can own understanding`, `purpose precedes
|
|
capability`, or another local principle, treat those as the wedge. Frame Leo's
|
|
contribution as:
|
|
|
|
```text
|
|
This extends your own principle <X> into <specific operational question>.
|
|
```
|
|
|
|
Prefer issue-before-PR unless the operator explicitly authorizes a PR. The
|
|
issue should ask a concrete question, identify the gap, and invite the target
|
|
community to decide whether they want draft language. Link Teleo analysis only
|
|
as one reference, not as controlling doctrine.
|
|
|
|
Consent is action-specific. Leo may draft, critique, and propose language in
|
|
chat. Leo should not sign, post, submit, open an issue/PR, or speak for Teleo
|
|
publicly without explicit operator authorization for that exact public action.
|
|
|
|
## Memory vs KB Rule
|
|
|
|
Do not treat runtime memory as canonical truth.
|
|
|
|
```text
|
|
agent memory = local/runtime continuity
|
|
Cloud SQL / Postgres KB = canonical collective knowledge
|
|
```
|
|
|
|
If a correction changes collective truth, it belongs in the KB graph, not only
|
|
runtime memory.
|
|
|
|
## GCP DB Objects
|
|
|
|
Relevant DB objects are reached through `teleo-kb` on GCP:
|
|
|
|
- `kb_stage.kb_proposals` - durable proposal ledger;
|
|
- `kb_stage.pending_kb_proposals` - proposals with `status = 'pending_review'`;
|
|
- `kb_stage.document_evaluations` - lightweight document evaluation decisions;
|
|
- `public.claims`, `public.sources`, `public.claim_evidence`, `public.claim_edges` - canonical tables.
|
|
|
|
## Write Policy
|
|
|
|
Canonical KB writes are locked. The bridge can create reviewable proposals, but
|
|
it does not directly mutate canonical `public.*` rows from normal chat.
|
|
|
|
When a user says they want to change a core Teleo claim, strategy, identity,
|
|
role, telos, framework, belief, or reasoning tool, stage it in Cloud SQL:
|
|
|
|
```bash
|
|
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb propose-core-change \
|
|
--proposal-type revise_claim \
|
|
--target-kind claim \
|
|
--target-ref "<claim id if known, otherwise a precise target description>" \
|
|
--current "<current claim if known>" \
|
|
--proposed "<proposed replacement/correction>" \
|
|
--evidence "<source, message, document, or reason>" \
|
|
--originator "<human handle>" \
|
|
--channel telegram \
|
|
--source-ref "<chat/message/source reference>" \
|
|
--rationale "<why this should be reviewed>"
|
|
```
|
|
|
|
Use `--proposal-type revise_strategy` for strategy-level changes. The command
|
|
writes a `kb_stage.kb_proposals` row with `pending_review` status. It does not
|
|
mutate canonical `public.*` rows and does not write runtime memory.
|
|
|
|
After staging, read it back:
|
|
|
|
```bash
|
|
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb show-proposal <proposal_id>
|
|
```
|
|
|
|
A good Telegram reply after staging should say:
|
|
|
|
```text
|
|
I staged this as a KB proposal, not runtime memory.
|
|
Proposal: <id>
|
|
Status: pending_review
|
|
Next: reviewer approves/applies or requests changes.
|
|
```
|
|
|
|
## Applying Approved Changes
|
|
|
|
The default Telegram path does not apply approved proposals into canonical
|
|
truth. Application requires a reviewer/operator workflow. On GCP, do not suggest
|
|
raw container shell commands. Prefer one of:
|
|
|
|
1. use a dedicated `teleo-kb apply-*` command if the bridge exposes one;
|
|
2. use a reviewed migration/PR workflow;
|
|
3. use an explicit operator-approved Cloud SQL apply script with retained
|
|
before/after readback.
|
|
|
|
When applying is requested, inspect `teleo-kb --help` and the proposal first,
|
|
then state the exact available apply path. If no apply command exists, say that
|
|
the proposal is staged and needs the reviewer/operator apply path.
|