---
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.