@fortemi/core

pnpm add @fortemi/core

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.

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:

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.

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, and compatibility metadata. Query helpers use v2 search and chunks text when the old top-level title/text fields are absent. 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

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

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.