@fortemi/core

Headless browser knowledge-management core powered by PGlite, typed repositories, semantic retrieval, and agent tool helpers

Build local-first knowledge apps where data stays in the browser on the user's device — no server, no account — with PostgreSQL-compatible storage, production-ready repositories, hybrid search primitives, portable Knowledge Shard archives, opt-in bring-your-own AI wiring, and bridge-ready tool metadata.

pnpm add @fortemi/core

Install · Why Fortemi · Quick Start · Surface · Tools · Docs · License

What @fortemi/core Is

@fortemi/core is the headless Fortemi runtime for browser applications. It gives your app a durable local archive backed by PGlite, typed repository classes, migrations, eventing, capability management, Knowledge Shard import/export, and tool helpers that can be called from UI code or bridge adapters.

Use it when you want the browser to own the user's working knowledge: notes, links, tags, collections, SKOS concepts, attachments, search history, revisions, generated metadata, and portable exports. No application server is required for the core archive path, and the same package can power React, non-React, extension, or embedded host integrations.

Why Fortemi Core

Most browser note and knowledge apps choose between a thin IndexedDB wrapper, a hosted database, or a custom sync protocol. Fortemi starts from a different premise: the browser can run a real PostgreSQL-compatible archive locally, then expose that archive through stable typed APIs and agent-readable tools.

| Need | What Fortemi provides | |---|---| | Local-first persistence | PGlite storage through OPFS, IndexedDB, or memory modes | | Queryable knowledge | SQL-backed repositories for notes, links, tags, collections, SKOS concepts, jobs, and search | | Retrieval quality | Full-text search, pgvector-backed semantic search, hybrid ranking, snippets, facets, and filters | | AI-ready workflows | Optional embeddings, local LLM capability discovery, job provenance, and fallback routing | | Portable archives | Knowledge Shard tar.gz import/export with set-scoped exports, chunked imports, checksums, BLAKE3-addressed blob sidecars, and profile-scoped conformance | | Agent integration | Manifest-backed tools and direct helper functions for bridge adapters and automation | | UI freedom | A headless package you can use from React, another framework, a browser extension, or a custom host |

What You Can Build

• Local-first notebooks, research workspaces, and personal knowledge bases
• Browser-only semantic search over user-owned notes and imported knowledge
• AI memory layers for agents that need structured retrieval, provenance, and portable state
• Web apps that can run from static hosting while still offering durable local storage
• Import/export pipelines using Knowledge Shards instead of app-specific backup formats
• Custom React, Svelte, Vue, extension, or embedded UIs on top of the same archive model

Architecture at a Glance

ArchiveManager opens a PGlite database, applies migrations, and scopes storage by archive name. Repository classes provide the canonical data-access layer. TypedEventBus keeps UI and background jobs in sync. Capability services track optional AI/runtime features. Tool helpers expose the same data model to bridges, local automations, and agent hosts.

Installation

pnpm add @fortemi/core
# or
npm install @fortemi/core

Runtime dependencies installed with the package:

| Dependency | Purpose | |---|---| | @electric-sql/pglite | PostgreSQL compiled to WASM, plus pgvector | | @noble/hashes | SHA hashing for content/integrity checks and BLAKE3 hashing for attachment blobs | | fflate | Tar/gzip handling for Knowledge Shards | | uuid | UUIDv7 identifiers | | zod | Runtime input validation for tool helpers |

Quick Start

import {
  ArchiveManager,
  NotesRepository,
  SearchRepository,
  TypedEventBus,
  registerServiceWorker,
} from '@fortemi/core'

const events = new TypedEventBus()
const archiveManager = new ArchiveManager('opfs', events)
const db = await archiveManager.open('default')

const notes = new NotesRepository(db, events)
const search = new SearchRepository(db)

const note = await notes.create({
  title: 'Hello',
  content: 'First note in the local archive.',
})

const results = await search.search('hello')

// Optional: register standalone service-worker routes.
await registerServiceWorker()

Static AIWG Index Search

Static documentation hosts can import the AIWG index helpers without pulling in PGlite, workers, shards, or browser storage:

import { createAiwgIndexController } from '@fortemi/core/aiwg-index'

const controller = createAiwgIndexController()
controller.loadIndex(await fetch('/aiwg-index.json').then((res) => res.json()))

const results = controller.query('deployment', {
  types: ['docs.page'],
  rank: true,
  snippets: true,
  limit: 10,
})

Use this subpath for Pagenary-style command palettes, static docs search, and vanilla JavaScript review surfaces. Its published dist/aiwg-index.js artifact is dependency-free, contains no import statements, and is kept below 50 KB so no-bundler consumers can vendor it verbatim.

Knowledge Shard conversion intentionally lives on the build-oriented subpath:

import {
  aiwgFortemiIndexFromKnowledgeShard,
  aiwgFortemiIndexToKnowledgeShard,
  aiwgFortemiIndexToKnowledgeShardWithReport,
} from '@fortemi/core/aiwg-index-shard'

That subpath owns the schema, tar/gzip, checksum, and UUID dependencies. The top-level @fortemi/core export also remains available for full archive/runtime integrations.

aiwgFortemiIndexToKnowledgeShard retains the reversible schema 1.2.0 core-v1 adapter. Native conversion uses the report-bearing entry point and the exact 2.0.0/full-v1 tuple:

const result = await aiwgFortemiIndexToKnowledgeShardWithReport(index)

if (!result.success) {
  console.table(result.losses)
  throw new Error('AIWG input cannot be represented as full-v1')
}
await importShard(db, result.archive!, { blobStore, conflictStrategy: 'replace' })

The full converter emits all 33 authority files and native note, relationship, SKOS, provenance, embedding, and graph records when the AIWG source is fully representable. Derived, defaulted, or omitted source information returns archive: null with typed losses; lossy output is never labeled full-v1.

PGlite uses the same rule for 2.0.0/full-v1. A previously imported full snapshot re-exports its complete logical file set; otherwise the exporter materializes all 33 files from live domain tables, requires every referenced attachment byte, and can add an Ed25519 publisher signature. Live values that cannot satisfy the authority schema, including non-768-dimensional embedding vectors, return archive: null with a typed capability loss.

PGlite advertises exact 2.0.0/full-v1 import and export only because schemas/knowledge-shard-v2.cross-repository.receipt.json binds the released PGlite and AIWG archives to clean repeated PGlite and Fortemi destinations, complete per-cell semantic/rejection coverage, immutable package and authority identities, and delivered CI. Advertisement is computed from that receipt at runtime; drifting any bound authority, archive, implementation, or Fortemi receipt disables the claim, while the verifier requires the packaged receipt bytes to match their declared digests. RecordStore remains record-v1 only. This receipt does not establish suite-wide portability or complete backup.

Supported-platform conformance

The authority-owned suite matrix treats Fortemi as the schema/API/runtime authority, @fortemi/core as the reusable conformance consumer, and HotM as an application consumer. Fortemi run 6393 passed the same receipt-bound contract on Linux x86_64, Linux arm64, and macOS arm64. Its React/Core participant is commit ccf96fad6025025293e40e250c85f088c8999d86, @fortemi/[email protected], with tgz SHA-256 e282f504a842261c3f598a7f2ee0d6a85e03dc213ddf545a18daf5f603a742cc and tar payload SHA-256 47482320b543307c2d44f3a87a2268ead6faf265c6bd38cf33011e0ac7f8e77a.

The supported claim is limited to the declared contract surface and exact Knowledge Shard 2.0.0/full-v1 tuple on those platform cells. Windows remains deferred to Fortemi #1096. This does not change the Fortemi #1081 NO-GO audit or prove complete backup, universal portability, launched GUI/native-dialog behavior, or RecordStore full-v1.

Knowledge Shard 2.0 treats absent, null, empty, and non-empty values as distinct authority states. PGlite persists core-v1 field presence in a transactional sidecar, while RecordStore carries its record-v1 projection and manifest state in the same atomic batch. Wildcard fields are tracked per array member, such as /attachments/0/reason. Import rejects unsupported states before mutation, and export rejects legacy rows whose original presence is indeterminate. The pinned local matrix receipt is schemas/knowledge-shard-v2.presence.receipt.json.

The AIWG index adapter accepts both aiwg.fortemi.index.export.v1 and aiwg.fortemi.index.export.v2 envelopes. The v1 record contract keeps the existing flat fields for filtering and search: facets, tags, concepts, relationships, and provenance. Static consumers that render metadata tabs can also read optional rich fields from full records:

• skos_concepts: concept ids plus labels, definitions, schemes, notation, URIs, alternate labels, and metadata.
• skos_relations: broader, narrower, related, or project-specific SKOS concept edges.
• provenance_events: W3C PROV-style activity records with agents, timestamps, source paths, confidence/privacy, and attributes.
• relationships[*].metadata: optional relationship labels, confidence, privacy, and structured metadata.

These fields are additive to aiwg.fortemi.index.record.v1. Version 2 records can also carry AIWG migration fields such as search, chunks, embeddings, source.origin, source.generated, source.checksum, source.updated_at, privacy.locality, operational_state, state_transfer, and compatibility metadata. Query helpers use v2 search and chunks text when the old top-level title/text fields are absent.

The reduced core-v1 converter maps directory prefixes from source.repo_relative_path to deterministic native collections and assigns each note to the leaf collection. A note tombstone is emitted only from an explicit state_transfer.deleted_at; operational_state remains provenance about an observed external system and never implies deletion. The full source record remains embedded in note metadata for reverse conversion. Existing consumers can ignore the v2 fields and continue querying the flat fields. Chunked indexes with a projection keep rich metadata in detail records; call getRecord(id) before rendering a metadata panel.

Large static indexes can use the chunked browser path instead of downloading one full aiwg.fortemi.index.export.v1 file. Host a manifest plus deterministic part files:

/search/aiwg-index/manifest.json
/search/aiwg-index/part-0000.json
/search/aiwg-index/part-0001.json

import {
  createAiwgFetchChunkLoader,
  createAiwgIndexController,
} from '@fortemi/core/aiwg-index'

const controller = createAiwgIndexController()
const manifest = await fetch('/search/aiwg-index/manifest.json').then((res) => res.json())

controller.loadChunkedIndex(
  manifest,
  createAiwgFetchChunkLoader('/search/aiwg-index/'),
  { maxCachedParts: 3 },
)

const page = await controller.queryChunked('', { offset: 100, limit: 25 })

Unfiltered browse requests fetch only the part files intersecting the requested offset and limit. Filtered or ranked searches scan part files to compute exact results, but the controller keeps only a bounded part cache and never sets a materialized full export in getIndex().

AIWG records can use project-specific string types such as aiwg.skill, aiwg.agent, aiwg.command, aiwg.rule, aiwg.flow, aiwg.bundle, aiwg.kb.page, aiwg.memory.entry, aiwg.issue, research.ref, and aiwg.research.profile. Validation still enforces required record fields, but it does not require unknown AIWG, research, KB, memory, issue, or documentation domains to collapse into aiwg.artifact.

For AIWG command-palette parity, opt into discovery ranking instead of the default deterministic substring lookup:

const ranked = controller.query('address the open issues', {
  searchProfile: 'aiwg-discovery',
  rank: true,
  includeMatches: true,
})

The discovery profile normalizes hyphen/space variants, strips common stopwords, boosts trigger and capability facets, and returns match reasons for UI debugging.

Chunked indexes also support graph navigation without loading a full export:

const neighbors = await controller.neighbors('aiwg:requirement:search', {
  direction: 'both',
  relationshipType: 'cites',
  relationshipDirection: 'downstream',
})

const graph = await controller.toCommunityGraphChunked()

Relationship edges preserve v2 source_path, target_path, and direction: 'upstream' | 'downstream' | 'related' values. Use direction: 'in' | 'out' | 'both' for graph orientation around a node and relationshipDirection for AIWG dependency/citation/profile/KB direction semantics. When scan parts are projected, relationship traversal scans the parts and lazy-loads detail records only when relationships are not present in the scan projection.

Static semantic search uses an optional sidecar contract:

import { buildAiwgStaticEmbeddingSet, queryAiwgHybridIndex } from '@fortemi/core/aiwg-index'

const embeddingSet = await fetch('/search/aiwg-index/embeddings.json').then((res) => res.json())
const queryEmbedding = await hostEmbed('workspace health check')
const semanticResults = queryAiwgHybridIndex(index, embeddingSet, 'health check', queryEmbedding)

// Node/CLI generation path. Supply any Node-safe model backend; @fortemi/core
// only writes the shared embedding-set graph format and does not require DOM or WebGL.
const cliEmbeddingSet = await buildAiwgStaticEmbeddingSet(index, {
  id: 'aiwg-cli-embeddings',
  backend: {
    model: 'local-node-embedder',
    dimensions: 384,
    embed: async (input) => nodeEmbed(input),
  },
})

aiwg.fortemi.embedding.set.v1 records the model, dimensions, granularity (title-summary, body, chunked-body, or a project value), source record IDs, and per-vector input hashes. Hosts provide query embeddings; @fortemi/core does not add a model runtime dependency for static AIWG search. The builder uses the same record text projection as static search, including attachment extracted_text, and records only attachment metadata references, never raw blob bytes.

What You Get

| Surface | Description | |---|---| | PGlite archive | opfs, idb, and memory persistence modes with migrations on open | | Repositories | Notes, search, tags, collections, links, SKOS concepts, attachments, embedding sets, graph helpers, jobs, and provenance | | Event bus | Typed subscriptions for note, job, archive, and capability events | | Capability system | Embeddings, local LLM, GPU detection, local-provider discovery, fallback routing | | Job queue | Server-compatible background workflow for revisions, titles, embeddings, concepts, and links | | Knowledge Shards | Tar.gz import/export with checksums, BLAKE3-addressed blob sidecars, progress callbacks, yielding imports, set-scoped embedding exports, and profile-scoped conformance | | Service-worker helpers | Route registration primitives for standalone browser integration |

Search and Knowledge Model

Fortemi's archive is more than note CRUD. The schema includes note bodies, generated titles, revision history, tags, collections, inter-note links, SKOS concept schemes, attachments, job provenance, and query history. Search can combine PostgreSQL full-text ranking with pgvector embeddings, then fuse scores for hybrid results.

That gives product teams a foundation for features users already expect from serious knowledge software: fast recall, related-note discovery, semantic retrieval, explainable provenance, import/export, and structured taxonomy support.

Tool Surface

FortemiToolManifest registers 10 bridge-visible Fortemi tools:

capture_knowledge, manage_note, search, get_note, list_notes, manage_tags, manage_collections, manage_links, manage_archive, manage_capabilities.

The package also exports 11 direct helper functions from @fortemi/core, including manageAttachments for attachment metadata and blob operations.

import { fortemiManifest } from '@fortemi/core'

const capabilities = fortemiManifest.toBridgeCapabilities()

Use the manifest when a host needs to advertise Fortemi operations to an agent runtime. Use the direct helper functions when your own code needs the same validated operations without going through a bridge layer.

Browser Storage

| Mode | Storage | Best for | |---|---|---| | opfs | Origin Private File System access-handle pool | Chrome and Edge production apps | | idb | IndexedDB-backed PGlite data directory | Firefox and broad compatibility | | memory | In-memory database | Tests, demos, restricted browser contexts |

Data stays in the selected browser storage mode unless your application explicitly exports it, imports it, or wires external providers. Optional AI capabilities are opt-in and can be routed to local WASM, local provider servers, OpenAI-compatible APIs, or host-provided integrations depending on your product requirements. API keys should live only in browser or machine secure storage; if secure storage is unavailable, do not persist them.

React Bindings

For React applications, install @fortemi/react. It wraps @fortemi/core with FortemiProvider, context access, worker-mode PGlite, graph visualization primitives, and the React hook surface.

pnpm add @fortemi/react @fortemi/core react

Documentation

• Repository API
• Integration guide
• Search guide
• Extending Fortemi
• Supply-chain controls

License

AGPL-3.0-only. See LICENSE.