@recallkit/web 0.1.1

package/src/hooks/useWallet.ts

@@ -0,0 +1,69 @@
+"use client";
+
+import { useCallback, useEffect } from "react";
+import { connectInjectedWallet, getGlmBalance, switchToArkivBraga } from "@/lib/wallet";
+import { getWalletStatus, saveWalletOwner } from "@/services/signerApi";
+import { appStore, useAppStore } from "@/stores/appStore";
+import { readError } from "@/utils/errors";
+
+let statusRequested = false;
+
+export function useWallet() {
+  const wallet = useAppStore((state) => state.wallet);
+
+  const refreshStatus = useCallback(async () => {
+    try {
+      const status = await getWalletStatus();
+      appStore.setState((state) => ({
+        wallet: { ...state.wallet, status },
+      }));
+    } catch (error) {
+      appStore.setState((state) => ({
+        wallet: {
+          ...state.wallet,
+          error: readError(error, "Unable to read wallet status."),
+        },
+      }));
+    }
+  }, []);
+
+  useEffect(() => {
+    if (statusRequested) return;
+    statusRequested = true;
+    void refreshStatus();
+  }, [refreshStatus]);
+
+  const connect = useCallback(async () => {
+    appStore.setState((state) => ({
+      wallet: { ...state.wallet, busy: true, error: undefined },
+    }));
+
+    try {
+      const account = await connectInjectedWallet();
+      await switchToArkivBraga();
+      const [status, balance] = await Promise.all([
+        saveWalletOwner(account),
+        getGlmBalance(account),
+      ]);
+
+      appStore.setState((state) => ({
+        wallet: { ...state.wallet, status, balance, busy: false },
+      }));
+    } catch (error) {
+      appStore.setState((state) => ({
+        wallet: {
+          ...state.wallet,
+          busy: false,
+          error: readError(error, "Wallet connection failed."),
+        },
+      }));
+    }
+  }, []);
+
+  return {
+    ...wallet,
+    connect,
+    refreshStatus,
+    balanceLow: wallet.balance !== undefined && Number(wallet.balance) <= 0,
+  };
+}

package/src/lib/api.ts

@@ -0,0 +1,71 @@
+type ApiGetOptions = {
+  ttlMs?: number;
+  force?: boolean;
+};
+
+type CacheEntry = {
+  expiresAt: number;
+  value: unknown;
+};
+
+const getCache = new Map<string, CacheEntry>();
+const inFlightGets = new Map<string, Promise<unknown>>();
+
+export async function apiGet<T>(path: string, options: ApiGetOptions = {}): Promise<T> {
+  const ttlMs = options.ttlMs ?? 0;
+  const now = Date.now();
+
+  if (!options.force && ttlMs > 0) {
+    const cached = getCache.get(path);
+    if (cached && cached.expiresAt > now) return cached.value as T;
+  }
+
+  if (!options.force) {
+    const inFlight = inFlightGets.get(path);
+    if (inFlight) return inFlight as Promise<T>;
+  }
+
+  const request = fetch(path, { cache: "no-store" })
+    .then(async (response) => {
+      if (!response.ok) throw new Error(await response.text());
+      const value = (await response.json()) as T;
+      if (ttlMs > 0) getCache.set(path, { value, expiresAt: Date.now() + ttlMs });
+      return value;
+    })
+    .finally(() => {
+      inFlightGets.delete(path);
+    });
+
+  inFlightGets.set(path, request);
+  return request;
+}
+
+export function invalidateApiCache(path?: string): void {
+  if (path) {
+    getCache.delete(path);
+    return;
+  }
+  getCache.clear();
+}
+
+export async function apiPost<T>(path: string, body: unknown): Promise<T> {
+  invalidateApiCache();
+  const response = await fetch(path, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (!response.ok) throw new Error(await response.text());
+  return response.json() as Promise<T>;
+}
+
+export async function apiPatch<T>(path: string, body: unknown): Promise<T> {
+  invalidateApiCache();
+  const response = await fetch(path, {
+    method: "PATCH",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (!response.ok) throw new Error(await response.text());
+  return response.json() as Promise<T>;
+}

package/src/lib/wallet.ts

@@ -0,0 +1,88 @@
+"use client";
+
+import { createWalletClient } from "@arkiv-network/sdk";
+import { braga } from "@arkiv-network/sdk/chains";
+import { createPublicClient, custom, formatEther, type Chain } from "viem";
+
+declare global {
+  interface Window {
+    ethereum?: {
+      request: (args: { method: string; params?: unknown[] | object }) => Promise<unknown>;
+    };
+  }
+}
+
+export const arkivBraga: Chain = {
+  id: Number(process.env.NEXT_PUBLIC_ARKIV_CHAIN_ID ?? "60138453102"),
+  name: "Arkiv Braga",
+  nativeCurrency: {
+    name: "GLM",
+    symbol: "GLM",
+    decimals: 18,
+  },
+  rpcUrls: {
+    default: {
+      http: ["https://braga.hoodi.arkiv.network/rpc"],
+    },
+  },
+  blockExplorers: {
+    default: {
+      name: "Arkiv Braga Explorer",
+      url: "https://explorer.braga.hoodi.arkiv.network",
+    },
+  },
+};
+
+export async function connectInjectedWallet(): Promise<`0x${string}`> {
+  if (!window.ethereum) throw new Error("No injected browser wallet was found.");
+  const accounts = (await window.ethereum.request({ method: "eth_requestAccounts" })) as string[];
+  const account = accounts[0];
+  if (!account?.startsWith("0x")) throw new Error("No wallet account was returned.");
+  return account as `0x${string}`;
+}
+
+export async function switchToArkivBraga(): Promise<void> {
+  if (!window.ethereum) throw new Error("No injected browser wallet was found.");
+
+  const chainId = `0x${arkivBraga.id.toString(16)}`;
+  try {
+    await window.ethereum.request({
+      method: "wallet_switchEthereumChain",
+      params: [{ chainId }],
+    });
+  } catch (switchError) {
+    console.info("Arkiv Braga chain switch failed, requesting chain add", switchError);
+    await window.ethereum.request({
+      method: "wallet_addEthereumChain",
+      params: [
+        {
+          chainId,
+          chainName: arkivBraga.name,
+          nativeCurrency: arkivBraga.nativeCurrency,
+          rpcUrls: arkivBraga.rpcUrls.default.http,
+          blockExplorerUrls: [arkivBraga.blockExplorers?.default.url],
+        },
+      ],
+    });
+  }
+}
+
+export async function getGlmBalance(account: `0x${string}`): Promise<string> {
+  if (!window.ethereum) throw new Error("No injected browser wallet was found.");
+  const publicClient = createPublicClient({
+    chain: arkivBraga,
+    transport: custom(window.ethereum),
+  });
+  const balance = await publicClient.getBalance({ address: account });
+  return formatEther(balance);
+}
+
+export async function createArkivBrowserWalletClient(account: `0x${string}`): Promise<unknown> {
+  if (!window.ethereum) throw new Error("No injected browser wallet was found.");
+
+  return createWalletClient({
+    account,
+    chain: braga,
+    transport: custom(window.ethereum),
+  });
+}

package/src/services/commitMemories.ts

@@ -0,0 +1,153 @@
+import {
+  createIndexCheckpoint,
+  createMemoryCommit,
+  createMemoryManifest,
+  createMemoryPack,
+} from "@recallkit/core/arkiv";
+import { DEFAULT_EXPIRES_IN } from "@recallkit/core/constants";
+import { encryptJson } from "@recallkit/core/crypto";
+import { hashScope } from "@recallkit/core/keys";
+import { normalizeMemoryScope } from "@recallkit/core/memory";
+import type {
+  MemoryCommitPayload,
+  MemoryIndexCheckpointPayload,
+  MemoryIndexEntry,
+  MemoryManifestPayload,
+  MemoryPackPayload,
+} from "@recallkit/core";
+import type { MemoryRecord } from "@recallkit/core/schemas";
+import { createArkivBrowserWalletClient } from "@/lib/wallet";
+import { completeCommit } from "./signerApi";
+import type { CommitEntityKeys, CommitPreviewData } from "./types";
+
+type CommitMemoriesInput = {
+  passphrase: string;
+  preview: CommitPreviewData;
+  selectedIds: string[];
+};
+
+export async function commitSelectedMemories({
+  passphrase,
+  preview,
+  selectedIds,
+}: CommitMemoriesInput): Promise<CommitEntityKeys> {
+  if (preview.memories.length === 0) {
+    throw new Error("No global or project memories are selected for Arkiv commit.");
+  }
+
+  const walletClient = await createArkivBrowserWalletClient(preview.signerWallet as `0x${string}`);
+  const commitId = `commit_${crypto.randomUUID()}`;
+  const now = new Date().toISOString();
+
+  const packPayload: MemoryPackPayload = {
+    schemaVersion: 1,
+    packId: `pack_${crypto.randomUUID()}`,
+    ownerWallet: preview.signerWallet,
+    commitId,
+    memories: preview.memories,
+    createdAt: now,
+  };
+
+  const encryptedPack = await encryptJson(packPayload, passphrase);
+  const packWrite = await createMemoryPack({
+    walletClient,
+    ownerWallet: preview.signerWallet,
+    encryptedPayload: encryptedPack,
+    scopeHash: await hashScope(scopeLabel(preview.memories[0])),
+    expiresIn: DEFAULT_EXPIRES_IN.PROJECT_MEMORY,
+  });
+
+  const newEntries = createIndexEntries(preview.memories, packWrite.entityKey);
+
+  const indexPayload: MemoryIndexCheckpointPayload = {
+    schemaVersion: 1,
+    checkpointId: `idx_${crypto.randomUUID()}`,
+    ownerWallet: preview.signerWallet,
+    entries: [...preview.baseIndexEntries, ...newEntries],
+    createdAt: now,
+  };
+  const encryptedIndex = await encryptJson(indexPayload, passphrase);
+  const indexWrite = await createIndexCheckpoint({
+    walletClient,
+    ownerWallet: preview.signerWallet,
+    encryptedPayload: encryptedIndex,
+    expiresIn: DEFAULT_EXPIRES_IN.PROJECT_MEMORY,
+  });
+
+  const commitPayload: MemoryCommitPayload = {
+    schemaVersion: 1,
+    commitId,
+    ownerWallet: preview.signerWallet,
+    message: `Approved ${preview.memories.length} RecallKit memories`,
+    addedMemoryIds: preview.memories.map((memory) => memory.id),
+    supersededMemoryIds: preview.conflicts.map((conflict) => conflict.conflictsWith),
+    packEntityKeys: [packWrite.entityKey],
+    indexCheckpointEntityKey: indexWrite.entityKey,
+    createdFrom: "skill",
+    approvedByUser: true,
+    createdAt: now,
+  };
+  const encryptedCommit = await encryptJson(commitPayload, passphrase);
+  const commitWrite = await createMemoryCommit({
+    walletClient,
+    ownerWallet: preview.signerWallet,
+    encryptedPayload: encryptedCommit,
+    expiresIn: DEFAULT_EXPIRES_IN.PROJECT_MEMORY,
+  });
+
+  const manifestPayload: MemoryManifestPayload = {
+    schemaVersion: 1,
+    ownerWallet: preview.signerWallet,
+    latestCommitId: commitId,
+    latestIndexCheckpointEntityKey: indexWrite.entityKey,
+    activePackEntityKeys: [packWrite.entityKey],
+    createdAt: now,
+  };
+  const encryptedManifest = await encryptJson(manifestPayload, passphrase);
+  const manifestWrite = await createMemoryManifest({
+    walletClient,
+    ownerWallet: preview.signerWallet,
+    encryptedPayload: encryptedManifest,
+    expiresIn: DEFAULT_EXPIRES_IN.LONG_TERM_MEMORY,
+  });
+
+  const entityKeys: CommitEntityKeys = {
+    memory_pack: packWrite.entityKey,
+    memory_index_checkpoint: indexWrite.entityKey,
+    memory_commit: commitWrite.entityKey,
+    memory_manifest: manifestWrite.entityKey,
+  };
+
+  await completeCommit({
+    pendingIds: preview.committablePendingIds.length ? preview.committablePendingIds : selectedIds,
+    indexCheckpoint: indexPayload,
+    packs: [{ ...packPayload, entityKey: packWrite.entityKey }],
+    entityKeys,
+  });
+
+  return entityKeys;
+}
+
+function createIndexEntries(memories: MemoryRecord[], packEntityKey: string): MemoryIndexEntry[] {
+  return memories.map((memory) => ({
+    memoryId: memory.id,
+    packEntityKey,
+    kind: memory.kind,
+    scope: normalizeMemoryScope(memory.scope),
+    summary: memory.summary,
+    keywords: memory.retrieval.keywords,
+    topics: memory.retrieval.topics,
+    semanticSummary: memory.retrieval.semanticSummary,
+    importance: memory.retrieval.importance,
+    confidence: memory.evidence.confidence,
+    status: memory.lifecycle.status,
+    createdAt: memory.lifecycle.createdAt,
+    ...(memory.lifecycle.updatedAt ? { updatedAt: memory.lifecycle.updatedAt } : {}),
+  }));
+}
+
+function scopeLabel(memory: MemoryRecord | undefined): string {
+  if (!memory) return "project:recallkit";
+  const scope = normalizeMemoryScope(memory.scope);
+  return `${scope.level}:${scope.projectId ?? scope.repoPath ?? scope.workspaceId ?? "default"}`;
+}

package/src/services/signerApi.ts

@@ -0,0 +1,67 @@
+import type { MemoryIndexEntry } from "@recallkit/core";
+import type { PendingMemoryCandidate } from "@recallkit/core/schemas";
+import { apiGet, apiPatch, apiPost } from "@/lib/api";
+import type { CachePack } from "@/stores/slices/memoryCacheSlice";
+import type { WalletStatus } from "@/stores/slices/walletSlice";
+import type { CommitEntityKeys, CommitPreviewData } from "./types";
+
+const WALLET_STATUS_TTL_MS = 5_000;
+const PENDING_MEMORY_TTL_MS = 2_000;
+const MEMORY_CACHE_TTL_MS = 30_000;
+
+export function getWalletStatus(): Promise<WalletStatus> {
+  return apiGet<WalletStatus>("/api/status", { ttlMs: WALLET_STATUS_TTL_MS });
+}
+
+export function saveWalletOwner(ownerWallet: string): Promise<WalletStatus> {
+  return apiPost<WalletStatus>("/api/status", { ownerWallet });
+}
+
+export async function getPendingMemories(options: { force?: boolean } = {}): Promise<PendingMemoryCandidate[]> {
+  const response = await apiGet<{ pending: PendingMemoryCandidate[] }>("/api/pending", {
+    ...(options.force ? { force: true } : {}),
+    ttlMs: PENDING_MEMORY_TTL_MS,
+  });
+  return response.pending;
+}
+
+export function updatePendingMemory(candidate: PendingMemoryCandidate): Promise<unknown> {
+  return apiPatch(`/api/pending/${candidate.id}`, {
+    text: candidate.text,
+    reason: candidate.reason,
+    importance: candidate.importance,
+    scope: candidate.scope,
+    scopeReason: candidate.scopeReason,
+    status: candidate.status,
+  });
+}
+
+export function deletePendingMemory(id: string): Promise<unknown> {
+  return apiPost(`/api/pending/${id}/delete`, {});
+}
+
+export async function getMemoryCache(): Promise<CachePack[]> {
+  const response = await apiGet<{ packs: CachePack[] }>("/api/memory-cache", {
+    ttlMs: MEMORY_CACHE_TTL_MS,
+  });
+  return response.packs;
+}
+
+export function buildCommitPreview(ids: string[]): Promise<CommitPreviewData> {
+  return apiPost<CommitPreviewData>("/api/commit/preview", { ids });
+}
+
+export function completeCommit(input: {
+  pendingIds: string[];
+  indexCheckpoint: {
+    schemaVersion: 1;
+    checkpointId: string;
+    ownerWallet: string;
+    entries: MemoryIndexEntry[];
+    createdAt: string;
+  };
+  packs: unknown[];
+  entityKeys: CommitEntityKeys;
+}): Promise<unknown> {
+  return apiPost("/api/commit/complete", input);
+}

package/src/services/types.ts

@@ -0,0 +1,22 @@
+import type { MemoryIndexEntry } from "@recallkit/core";
+import type { MemoryRecord } from "@recallkit/core/schemas";
+
+export type CommitPreviewData = {
+  ok: true;
+  signerWallet: string;
+  network: string;
+  selectedCount: number;
+  committablePendingIds: string[];
+  sessionDraftCount: number;
+  entities: string[];
+  estimatedWrites: number;
+  encryption: "enabled";
+  memories: MemoryRecord[];
+  conflicts: Array<{ memoryId: string; conflictsWith: string; reason: string }>;
+  baseIndexEntries: MemoryIndexEntry[];
+};
+
+export type CommitEntityKeys = Record<
+  "memory_pack" | "memory_index_checkpoint" | "memory_commit" | "memory_manifest",
+  string
+>;

package/src/stores/appStore.ts

@@ -0,0 +1,18 @@
+"use client";
+
+import { createStore } from "./createStore";
+import { memoryCacheInitialState, type MemoryCacheSlice } from "./slices/memoryCacheSlice";
+import { pendingMemoryInitialState, type PendingMemorySlice } from "./slices/pendingMemorySlice";
+import { walletInitialState, type WalletSlice } from "./slices/walletSlice";
+
+export type AppState = WalletSlice & PendingMemorySlice & MemoryCacheSlice;
+
+export const appStore = createStore<AppState>({
+  ...walletInitialState,
+  ...pendingMemoryInitialState,
+  ...memoryCacheInitialState,
+});
+
+export function useAppStore<TSelected>(selector: (state: AppState) => TSelected): TSelected {
+  return appStore.useStore(selector);
+}

package/src/stores/createStore.ts

@@ -0,0 +1,41 @@
+"use client";
+
+import { useSyncExternalStore } from "react";
+
+type Listener = () => void;
+type SetState<TState> = Partial<TState> | ((state: TState) => Partial<TState>);
+
+export type StoreApi<TState> = {
+  getState: () => TState;
+  setState: (next: SetState<TState>) => void;
+  subscribe: (listener: Listener) => () => void;
+  useStore: <TSelected>(selector: (state: TState) => TSelected) => TSelected;
+};
+
+export function createStore<TState>(initialState: TState): StoreApi<TState> {
+  let state = initialState;
+  const listeners = new Set<Listener>();
+
+  function getState() {
+    return state;
+  }
+
+  function setState(next: SetState<TState>) {
+    state = {
+      ...state,
+      ...(typeof next === "function" ? next(state) : next),
+    };
+    listeners.forEach((listener) => listener());
+  }
+
+  function subscribe(listener: Listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  }
+
+  function useStore<TSelected>(selector: (current: TState) => TSelected): TSelected {
+    return useSyncExternalStore(subscribe, () => selector(state), () => selector(initialState));
+  }
+
+  return { getState, setState, subscribe, useStore };
+}

package/src/stores/slices/memoryCacheSlice.ts

@@ -0,0 +1,29 @@
+export type CachedMemory = {
+  id: string;
+  kind: string;
+  summary: string;
+  retrieval: { importance: number };
+  evidence: { confidence: number; source: string };
+};
+
+export type CachePack = {
+  memories: CachedMemory[];
+};
+
+export type MemoryCacheSlice = {
+  memoryCache: {
+    memories: CachedMemory[];
+    loaded: boolean;
+    loading: boolean;
+    error: string | undefined;
+  };
+};
+
+export const memoryCacheInitialState: MemoryCacheSlice = {
+  memoryCache: {
+    memories: [],
+    loaded: false,
+    loading: false,
+    error: undefined,
+  },
+};

package/src/stores/slices/pendingMemorySlice.ts

@@ -0,0 +1,21 @@
+import type { PendingMemoryCandidate } from "@recallkit/core/schemas";
+
+export type PendingMemorySlice = {
+  pendingMemory: {
+    items: PendingMemoryCandidate[];
+    selectedIds: string[];
+    refreshing: boolean;
+    loaded: boolean;
+    error: string | undefined;
+  };
+};
+
+export const pendingMemoryInitialState: PendingMemorySlice = {
+  pendingMemory: {
+    items: [],
+    selectedIds: [],
+    refreshing: false,
+    loaded: false,
+    error: undefined,
+  },
+};

package/src/stores/slices/walletSlice.ts

@@ -0,0 +1,24 @@
+export type WalletStatus = {
+  connected: boolean;
+  ownerWallet?: string;
+  network?: string;
+  approvalAppUrl: string;
+};
+
+export type WalletSlice = {
+  wallet: {
+    status: WalletStatus | undefined;
+    balance: string | undefined;
+    busy: boolean;
+    error: string | undefined;
+  };
+};
+
+export const walletInitialState: WalletSlice = {
+  wallet: {
+    status: undefined,
+    balance: undefined,
+    busy: false,
+    error: undefined,
+  },
+};

package/src/styles/base.css

@@ -0,0 +1,61 @@
+* {
+  box-sizing: border-box;
+}
+
+html {
+  background: var(--bg);
+}
+
+html,
+body {
+  margin: 0;
+  min-height: 100%;
+  color: var(--text);
+  font-family: var(--font-sans), Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  font-feature-settings: "ss01", "cv11";
+}
+
+body {
+  background: transparent;
+  position: relative;
+}
+
+body::before {
+  content: "";
+  position: fixed;
+  inset: 0;
+  background-image: url("/textures/bg-scene.png");
+  background-repeat: no-repeat;
+  background-size: cover;
+  background-position: center;
+  opacity: 0.35;
+  pointer-events: none;
+  z-index: 0;
+}
+
+body::after {
+  content: "";
+  position: fixed;
+  inset: 0;
+  background:
+    radial-gradient(ellipse at center, rgba(20, 20, 20, 0.0) 0%, rgba(20, 20, 20, 0.25) 100%);
+  pointer-events: none;
+  z-index: 0;
+}
+
+.shell {
+  position: relative;
+  z-index: 1;
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+
+button,
+input,
+select,
+textarea {
+  font: inherit;
+}