Fact Store
@twonines/fact-storev2026.07.13.1
Security Notice
This extension includes AI agent skills that can modify AI assistant behavior. Review the skill files before installing.
01README
Stores, validates, and serves organizational facts for AI agent consumption. Supports a propose→review→activate lifecycle with adversarial validation (ferret/mole pattern). Facts are relational truths about infrastructure, repositories, services, teams, and their connections. Ships with three agent skills — propose-facts and review-proposals drive the discovery and review loops (ferret/mole); consult-facts closes the loop as the consumer role, querying facts before engineering work and detecting drift.
02Models
@twonines/fact-storev2026.07.13.1mod.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| embedUrl? | string | OpenAI-compatible embeddings endpoint (required for export/search methods). |
| embedToken? | string | Bearer token for the embeddings API (required for export/search methods). |
| embedModel? | string | Embedding model ID (default: text-embedding-3-small). |
| embedDim? | number | Vector dimension (default: 1536). |
| outputPath? | string | Path for the exported SQLite db (default: ~/.jitter/facts.db). |
fn propose(kind: string, scope: string, value: unknown, proposedBy: string, evidence?: array, supersedesFactId?: string)
Submit a candidate fact for adversarial review. Called by discovery agents (ferret).
| Argument | Type | Description |
|---|---|---|
| kind | string | Fact kind (e.g. repository_deploys_to_account) |
| scope | string | Scope: global or narrower |
| value | unknown | The fact value (string, boolean, array, or object) |
| proposedBy | string | Agent or human identifier |
| evidence? | array | References to scan data or other sources |
| supersedesFactId? | string | ID of an existing active fact this proposal corrects, if any. |
fn activate(proposalId: string, reviewedBy: string)
Promote a proposal to an active fact. Called by reviewer agents (mole).
| Argument | Type | Description |
|---|---|---|
| proposalId | string | ID of the proposal to activate |
| reviewedBy | string | Reviewer agent or human identifier |
fn reject(proposalId: string, reason: string, reviewedBy: string)
Reject a proposal with feedback. Called by reviewer agents (mole).
| Argument | Type | Description |
|---|---|---|
| proposalId | string | ID of the proposal to reject |
| reason | string | Why this proposal was rejected — actionable feedback |
| reviewedBy | string | Reviewer agent or human identifier |
fn withdraw(proposalId: string)
Retract a proposal. Called by the proposing agent after acknowledging rejection feedback.
| Argument | Type | Description |
|---|---|---|
| proposalId | string | ID of the proposal to withdraw |
fn query(scope?: string, hints?: array, kinds?: array, limit: number)
Assemble a truth packet of relevant constraints and facts for a given scope/task.
| Argument | Type | Description |
|---|---|---|
| scope? | string | Repo path, service name, or entity identity to scope results |
| hints? | array | Task keywords for relevance matching |
| kinds? | array | Filter to specific fact kinds |
| limit | number | Maximum facts to return |
fn list_proposals(status: enum, offset: number, limit: number)
List proposals filtered by status. Supports pagination via offset+limit.
| Argument | Type | Description |
|---|---|---|
| status | enum | |
| offset | number | Number of matching proposals to skip (for pagination) |
| limit | number | Maximum proposals to return (max 500) |
fn list_facts(scope?: string, kind?: string, identityValue?: string, offset: number, limit: number)
List active facts, optionally filtered by scope or kind.
| Argument | Type | Description |
|---|---|---|
| scope? | string | Filter by scope |
| kind? | string | Filter by fact kind |
| identityValue? | string | Filter by subject identity |
| offset | number | Number of matching facts to skip (for pagination) |
| limit | number | Maximum facts to return (max 500) |
fn add_constraint(kind: string, scope: string, rule: string, rationale?: string, appliesTo?: array)
Add a behavioral constraint (human-curated rule). Not derived from evidence — authored by people.
| Argument | Type | Description |
|---|---|---|
| kind | string | Constraint kind: process, required_execution_path, naming_convention, security_boundary, deployment_rule |
| scope | string | |
| rule | string | The constraint rule text |
| rationale? | string | Why this constraint exists |
| appliesTo? | array | Tags for matching: language names, tool names, repo patterns |
fn retire_constraint(constraintId: string)
Retire a constraint that no longer applies. Constraints are
| Argument | Type | Description |
|---|---|---|
| constraintId | string | ID of the constraint to retire |
fn retire_fact(factId: string, reason: string, supersededByFactId?: string)
Retire or supersede an active fact that's no longer accurate.
| Argument | Type | Description |
|---|---|---|
| factId | string | ID of the fact to retire (its own id field, from query/list_facts output) |
| reason | string | Why this fact is no longer accurate |
| supersededByFactId? | string | ID of the fact that replaces this one. If set, status becomes |
fn coverage_gaps(discoveredRepos?: array, indexedRepos?: array, limit: number)
Analyze the fact store for knowledge gaps — repos with no facts,
| Argument | Type | Description |
|---|---|---|
| discoveredRepos? | array | List of known repo paths. If omitted, analyzes only repos already in the fact store. |
| indexedRepos? | array | List of repos that have been indexed (have a searchable db). Gaps flagged for unindexed repos. |
| limit | number | Max gaps to return, prioritized by impact. |
fn export()
Export all active facts and constraints to a local SQLite database
fn search(query: string, limit: number)
Hybrid FTS5 + vector search over the current exported index —
| Argument | Type | Description |
|---|---|---|
| query | string | Search query — natural language or keywords |
| limit | number | Max results per category (facts, constraints). |
Resources
fact(infinite)— An accepted, active truth claim about an entity
proposal(infinite)— A candidate fact awaiting review
constraint(infinite)— A human-curated behavioral rule
truth-packet(1h)— Assembled context for agent consumption
proposal-list(1h)— Filtered list of proposals
fact-list(1h)— Filtered list of facts
coverage-gaps(1h)— Analysis of knowledge gaps for curiosity-driven discovery
export-state(infinite)— Result of the last fact export to SQLite
index(infinite)— The exported SQLite database bytes (base64), stored as a portable
search-results(1h)— Hybrid FTS5 + vector search results against the current index
03Skills
propose-facts2 files
review-proposals2 files
consult-facts2 files
04Previous Versions
2026.07.12.2Jul 12, 2026
2026.07.12.1Jul 12, 2026
Modified 1 models
2026.07.10.2Jul 10, 2026
2026.07.10.1Jul 10, 2026
Modified 1 models. Added 1 skills
2026.07.09.2Jul 9, 2026
2026.07.09.1Jul 9, 2026
2026.07.08.3Jul 8, 2026
2026.07.08.2Jul 8, 2026
2026.07.08.1Jul 8, 2026
Modified 1 models
2026.07.03.1Jul 3, 2026
2026.07.02.1Jul 2, 2026
05Stats
A
100 / 100
Downloads
6
Archive size
158.8 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned
06Platforms
07Labels