@recallkit/core

Core domain logic for RecallKit. This package is intentionally framework-free so it can be used by the web signer, daemon, CLI, skill scripts.

Domain Map

src/
  constants.ts       Project constants, guide entity type names, default expirations
  types.ts           Cross-domain payload and Arkiv-facing types
  guide/             User Guide and Project Context schemas, patches, context packs
  memory/            Memory candidate and MemoryRecord lifecycle
  retrieval/         Query understanding, ranking, context packs
  crypto/            Passphrase encryption and hashing helpers
  arkiv/             Arkiv SDK payload loading, entity attributes, writes
  storage/           Local .recallkit paths, config, pending store, cache store

Public Import Surface

Prefer these imports from apps and packages:

import { buildGuideContextPack } from "@recallkit/core/guide";
import { readPendingGuidePatches } from "@recallkit/core/storage";
import { encryptJson } from "@recallkit/core/crypto";
import { createGuideSnapshot } from "@recallkit/core/arkiv";
import type { GuideSnapshot } from "@recallkit/core/guide";

Subpath exports are grouped by domain:

| Export | Purpose | | --- | --- | | @recallkit/core | Main public API. | | @recallkit/core/guide | Guide snapshots, guide patches, and context-pack shaping. | | @recallkit/core/memory | Candidate compilation, scoring, conflict, consolidation. | | @recallkit/core/retrieval | Search, ranking, context packs. | | @recallkit/core/crypto | Encryption and key helpers. | | @recallkit/core/arkiv | Arkiv attributes and write helpers. | | @recallkit/core/storage | Local config, guide patch, guide cache, and legacy memory stores. | | @recallkit/core/session | Wallet-session EIP-712 message types. | | @recallkit/core/schemas | Memory schema types. |

Browser code should prefer the focused crypto, arkiv, keys, constants, and type-only imports. storage uses Node filesystem APIs and is intended for the signer API, daemon, CLI.

Architectural Boundaries

• memory/ has no Arkiv dependency. It turns user/agent text into structured memory records and index metadata.
• retrieval/ consumes committed memory/index data. It does not write local files or Arkiv entities.
• crypto/ only handles encryption, decryption, hashing, and byte conversion.
• arkiv/ knows about Arkiv entity attributes, SDK payload conversion, and write calls.
• storage/ owns local .recallkit JSON files.

The durable write path remains wallet-native: the approval app encrypts payloads and signs Arkiv writes with the connected browser wallet. Do not expose keyed RPC URLs with NEXT_PUBLIC_*.

Local Files

RecallKit local state is rooted at RECALLKIT_DATA_DIR when set, otherwise the current working directory:

.recallkit/

Files:

.recallkit/config.json
.recallkit/session.json
.recallkit/guide-patches/<wallet>.json
.recallkit/guides/<wallet>/global.json
.recallkit/guides/<wallet>/project-<project>.json

Legacy unscoped .recallkit/pending.json files are imported into the signed-in wallet inbox by the daemon migration route.