> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fliiq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Institutional Knowledge System (IKS)

> Capture decision rationale, not just facts

Most AI agents treat every session as a blank slate. They can follow instructions, but they have no persistent understanding of *why* decisions were made, what constraints drove a particular approach, or what business rules informed a specific choice. Every session starts from zero institutional understanding.

IKS solves this. It captures decision rationale as a natural byproduct of doing work — when agents ask you for guidance, when they make non-trivial decisions, and when domain-specific reasoning surfaces during execution.

## Knowledge Records

Every piece of captured knowledge is stored as a structured **rationale record** with four types:

| Type          | What It Captures             | Example                                                                             |
| ------------- | ---------------------------- | ----------------------------------------------------------------------------------- |
| `decision`    | What was chosen and why      | "Use Stripe webhooks for refund automation because manual processing doesn't scale" |
| `constraint`  | Rules that must be respected | "All preventive care claims must bypass cost-sharing per ACA Section 2713"          |
| `heuristic`   | Learned best practices       | "Batch API calls in groups of 50 — larger batches hit rate limits"                  |
| `domain_rule` | Business or regulatory rules | "EU customers require GDPR-compliant data deletion within 30 days of request"       |

Each record includes:

* **context** — where this knowledge applies
* **decision** — what was decided or what the rule states
* **rationale** — why, with full reasoning
* **alternatives\_considered** — what else was evaluated and why it was rejected
* **confidence** — how certain the source is (0.0–1.0)
* **domain** — searchable domain tag (e.g. `billing`, `compliance`, `infrastructure`)
* **tags** — additional searchable labels

## How Knowledge Gets Captured

### Human-in-the-Loop

The highest-signal capture mechanism. When Fliiq surfaces a question during a task, it has identified genuine uncertainty. Your response — the domain knowledge, business context, or preference you share — gets persisted as a structured record. The agent reflects back its understanding, you confirm, and it's saved.

This feels like a natural part of the agent confirming it understood you. The only difference is the confirmed understanding gets persisted permanently.

### Agent Decisions

When the agent makes a non-trivial decision during execution, it can emit a rationale record. Not every decision gets captured — only when the agent is weighing multiple approaches against constraints, reasoning about *why* something should work a certain way, or making an assumption it cannot verify.

### Agent Inference

The agent can also infer knowledge from patterns it observes. If it encounters the same constraint repeatedly, it can synthesize a heuristic record capturing the pattern for future reference.

## Querying Knowledge

Fliiq automatically retrieves relevant knowledge at the right moments:

* **Pre-task:** When starting work, Fliiq loads domain-relevant knowledge based on the task description.
* **Pre-modification:** Before modifying a file, Fliiq checks for rationale records anchored to that code.
* **On uncertainty:** When confidence drops, Fliiq checks existing knowledge before asking you.

You can also query explicitly using the `knowledge_query` skill:

```
Search for all billing-related constraints
→ fliiq uses knowledge_query with domain="billing", type="constraint"

Find knowledge anchored to a specific file
→ fliiq uses knowledge_query with anchor_file="src/api/payments.py"

Search by keyword
→ fliiq uses knowledge_query with keyword="refund"
```

## Code Anchoring & Drift Detection

Knowledge records can be anchored to specific files and line ranges. When you anchor a record, Fliiq computes a SHA-256 hash of the anchored content. On subsequent retrievals, it compares the current hash against the stored one — if the code has changed, the record is flagged as potentially stale.

This is the "don't break things you don't understand" mechanism. Before modifying code with associated rationale, the agent reads and considers the knowledge. If the proposed change would violate a recorded constraint, it flags this rather than proceeding blindly.

## Skills Reference

| Skill              | Purpose                                                                                      |
| ------------------ | -------------------------------------------------------------------------------------------- |
| `knowledge_save`   | Save a structured knowledge record with rationale, alternatives, and optional anchoring      |
| `knowledge_query`  | Search by keyword, domain, file anchor, or tags — results ranked by relevance and confidence |
| `knowledge_update` | Update confidence, text, or tags on an existing record; soft-delete expired records          |

## Storage

Knowledge records are stored locally:

```
~/.fliiq/knowledge/
├── records/          # One JSON file per record (UUID-based)
└── index/
    ├── domain.json   # Domain → record ID lookup
    ├── tags.json     # Tag → record ID lookup
    └── anchors.json  # File path → record ID lookup
```

All data stays on your machine. No cloud sync, no external dependencies.