@recallkit/web 0.1.1

package/src/components/inbox/EmptyInbox.tsx

@@ -0,0 +1,20 @@
+export function EmptyInbox() {
+  return (
+    <div className="tile">
+      <div style={{ color: "var(--ink)", fontSize: 14.5, fontWeight: 500 }}>
+        No memory drafts yet.
+      </div>
+      <div className="body-dim" style={{ marginTop: 6 }}>
+        Memory drafts show up here when an agent runs the{" "}
+        <code style={{ color: "var(--accent)", fontFamily: "var(--font-mono), monospace" }}>
+          suggest-memory
+        </code>{" "}
+        skill script. Try this in your agent session:
+      </div>
+      <code className="snippet">
+        <span className="snippet__prompt">›</span>
+        Remember that I prefer wallet-native Arkiv writes and batch memory commits.
+      </code>
+    </div>
+  );
+}

package/src/components/inbox/InboxStats.tsx

@@ -0,0 +1,41 @@
+import type { PendingMemoryCandidate } from "@recallkit/core/schemas";
+
+type Props = {
+  pending: PendingMemoryCandidate[];
+  selectedCount: number;
+};
+
+export function InboxStats({ pending, selectedCount }: Props) {
+  const highest = pending.length
+    ? Math.max(...pending.map((c) => c.importance)).toFixed(2)
+    : "none";
+
+  return (
+    <div className="stat-grid">
+      <div className="stat-grid__cell">
+        <div className="stat-grid__label">Drafts</div>
+        <div className="stat-grid__value">{pending.length}</div>
+      </div>
+      <div className="stat-grid__cell">
+        <div className="stat-grid__label">Selected</div>
+        <div className="stat-grid__value stat-grid__value--accent">{selectedCount}</div>
+      </div>
+      <div className="stat-grid__cell">
+        <div className="stat-grid__label">Kinds</div>
+        <div className="stat-grid__value stat-grid__value--mono">
+          {kindSummary(pending) || "none"}
+        </div>
+      </div>
+      <div className="stat-grid__cell">
+        <div className="stat-grid__label">Top importance</div>
+        <div className="stat-grid__value">{highest}</div>
+      </div>
+    </div>
+  );
+}
+
+function kindSummary(pending: PendingMemoryCandidate[]): string {
+  if (pending.length === 0) return "";
+  const kinds = new Set(pending.map((c) => c.kind));
+  return [...kinds].slice(0, 3).join(", ");
+}

package/src/components/inbox/MemoryCandidateList.tsx

@@ -0,0 +1,90 @@
+import { normalizeMemoryScope } from "@recallkit/core/memory";
+import type { PendingMemoryCandidate } from "@recallkit/core/schemas";
+import { MemoryCandidateRow } from "./MemoryCandidateRow";
+
+type Props = {
+  candidates: PendingMemoryCandidate[];
+  selectedIds: Set<string>;
+  onToggle: (id: string) => void;
+  onChange: (candidate: PendingMemoryCandidate) => void;
+  onSave: (candidate: PendingMemoryCandidate) => void;
+  onApprove: (candidate: PendingMemoryCandidate) => void;
+  onReject: (id: string) => void;
+};
+
+export function MemoryCandidateList({
+  candidates,
+  selectedIds,
+  onToggle,
+  onChange,
+  onSave,
+  onApprove,
+  onReject,
+}: Props) {
+  const selectableCandidates = candidates.filter(isSelectableCandidate);
+  const total = candidates.length;
+  const selectableTotal = selectableCandidates.length;
+  const selectedSelectableCount = selectableCandidates.filter((candidate) =>
+    selectedIds.has(candidate.id),
+  ).length;
+  const allSelected = selectableTotal > 0 && selectedSelectableCount === selectableTotal;
+  const someSelected = selectedSelectableCount > 0 && !allSelected;
+
+  const toggleAll = () => {
+    if (allSelected) {
+      selectableCandidates.forEach((candidate) => {
+        if (selectedIds.has(candidate.id)) onToggle(candidate.id);
+      });
+      return;
+    }
+
+    selectableCandidates.forEach((candidate) => {
+      if (!selectedIds.has(candidate.id)) onToggle(candidate.id);
+    });
+  };
+
+  return (
+    <div className="candidate-list">
+      <div className="candidate-list__toolbar">
+        <label className="candidate-list__select-all">
+          <input
+            type="checkbox"
+            className="check"
+            checked={allSelected}
+            ref={(el) => {
+              if (el) el.indeterminate = someSelected;
+            }}
+            onChange={toggleAll}
+            aria-label={allSelected ? "Deselect all" : "Select all"}
+          />
+          <span>
+            {selectedSelectableCount > 0
+              ? `${selectedSelectableCount} of ${selectableTotal} selected`
+              : `${total} candidate${total === 1 ? "" : "s"}`}
+          </span>
+        </label>
+        <span className="candidate-list__sort">Sorted by importance ↓</span>
+      </div>
+
+      <div className="candidate-list__items">
+        {candidates.map((candidate) => (
+          <MemoryCandidateRow
+            key={candidate.id}
+            candidate={candidate}
+            selected={selectedIds.has(candidate.id)}
+            selectable={isSelectableCandidate(candidate)}
+            onToggle={() => onToggle(candidate.id)}
+            onChange={onChange}
+            onSave={() => onSave(candidate)}
+            onApprove={() => onApprove(candidate)}
+            onReject={() => onReject(candidate.id)}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function isSelectableCandidate(candidate: PendingMemoryCandidate): boolean {
+  return candidate.status === "approved" && normalizeMemoryScope(candidate.scope).level !== "session";
+}

package/src/components/inbox/MemoryCandidateRow.tsx

@@ -0,0 +1,195 @@
+import { normalizeMemoryScope, reasonForScope } from "@recallkit/core/memory";
+import type { MemoryScopeLevel, PendingMemoryCandidate } from "@recallkit/core/schemas";
+import { formatScopeLabel, formatTimeAgo, percent } from "@/utils/format";
+
+type Props = {
+  candidate: PendingMemoryCandidate;
+  selected: boolean;
+  selectable: boolean;
+  onToggle: () => void;
+  onChange: (candidate: PendingMemoryCandidate) => void;
+  onSave: () => void;
+  onApprove: () => void;
+  onReject: () => void;
+};
+
+const SCOPE_OPTIONS: Array<{ level: MemoryScopeLevel; label: string }> = [
+  { level: "global", label: "Global" },
+  { level: "project", label: "Current Project" },
+  { level: "session", label: "Session" },
+];
+
+export function MemoryCandidateRow({
+  candidate,
+  selected,
+  selectable,
+  onToggle,
+  onChange,
+  onSave,
+  onApprove,
+  onReject,
+}: Props) {
+  const importancePct = percent(candidate.importance);
+  const confidencePct = percent(candidate.confidence);
+  const scope = normalizeMemoryScope(candidate.scope);
+
+  function updateScopeLevel(level: MemoryScopeLevel) {
+    const nextScope = normalizeMemoryScope({
+      ...scope,
+      level,
+      ...(level === "project" && scope.projectId ? { projectId: scope.projectId } : {}),
+    });
+    onChange({ ...candidate, scope: nextScope, scopeReason: reasonForScope(nextScope) });
+  }
+
+  function updateProjectId(projectId: string) {
+    const nextScope = normalizeMemoryScope({ ...scope, level: "project", projectId });
+    onChange({ ...candidate, scope: nextScope, scopeReason: reasonForScope(nextScope) });
+  }
+
+  return (
+    <article className={`candidate${selected ? " is-selected" : ""}`}>
+      <div className="candidate__gutter">
+        <input
+          type="checkbox"
+          className="check"
+          checked={selected}
+          disabled={!selectable}
+          onChange={onToggle}
+          aria-label={selectable ? "Select memory" : "Session memory stays local"}
+        />
+      </div>
+
+      <div className="candidate__body">
+        <header className="candidate__head">
+          <div className="candidate__tags">
+            <span className={`kind-pill kind-pill--${candidate.kind}`}>
+              <span className="kind-pill__dot" aria-hidden="true" />
+              {candidate.kind}
+            </span>
+            <span className="scope-chip">{formatScopeLabel(scope)}</span>
+            <span className="tag-chip">{candidate.status}</span>
+            {candidate.tags.slice(0, 4).map((tag) => (
+              <span key={tag} className="tag-chip">
+                #{tag}
+              </span>
+            ))}
+            {candidate.tags.length > 4 ? (
+              <span className="tag-chip tag-chip--muted">+{candidate.tags.length - 4}</span>
+            ) : null}
+          </div>
+          <div className="candidate__attribution">
+            {candidate.createdByAgent ? (
+              <span className="candidate__agent">{candidate.createdByAgent}</span>
+            ) : null}
+            <time
+              className="candidate__time"
+              dateTime={candidate.createdAt}
+              title={new Date(candidate.createdAt).toLocaleString()}
+            >
+              {formatTimeAgo(candidate.createdAt)}
+            </time>
+          </div>
+        </header>
+
+        <textarea
+          className="candidate-text"
+          value={candidate.text}
+          onChange={(event) => onChange({ ...candidate, text: event.target.value })}
+        />
+
+        <div className="candidate-scope">
+          <div className="candidate-scope__head">
+            <span className="candidate__reason-label">Scope</span>
+            <span className="candidate-scope__value">{formatScopeLabel(scope)}</span>
+          </div>
+          <div className="scope-segment" role="group" aria-label="Memory scope">
+            {SCOPE_OPTIONS.map((option) => (
+              <button
+                key={option.level}
+                type="button"
+                className={scope.level === option.level ? "scope-segment__button is-active" : "scope-segment__button"}
+                onClick={() => updateScopeLevel(option.level)}
+              >
+                {option.label}
+              </button>
+            ))}
+          </div>
+          {scope.level === "project" ? (
+            <label className="candidate-scope__project">
+              <span>Project</span>
+              <input
+                value={scope.projectId ?? ""}
+                onChange={(event) => updateProjectId(event.target.value)}
+                placeholder="recallkit"
+              />
+            </label>
+          ) : null}
+          {candidate.scopeReason ? <p className="candidate-scope__reason">{candidate.scopeReason}</p> : null}
+          {scope.level === "session" ? (
+            <p className="candidate-scope__reason">Session memories stay local and are skipped by Arkiv commits.</p>
+          ) : null}
+        </div>
+
+        {candidate.reason ? (
+          <div className="candidate__reason">
+            <span className="candidate__reason-label">Reason</span>
+            <p>{candidate.reason}</p>
+          </div>
+        ) : null}
+
+        <footer className="candidate__foot">
+          <div className="candidate__scores">
+            <ScoreRow label="Importance" value={candidate.importance} pct={importancePct} />
+            <ScoreRow
+              label="Confidence"
+              value={candidate.confidence}
+              pct={confidencePct}
+              variant="dim"
+            />
+          </div>
+
+          <div className="candidate__actions">
+            <button type="button" className="row-action" onClick={onSave}>
+              Save edits
+            </button>
+            {candidate.status !== "approved" && scope.level !== "session" ? (
+              <button type="button" className="row-action" onClick={onApprove}>
+                Approve
+              </button>
+            ) : null}
+            <button
+              type="button"
+              className="row-action row-action--danger"
+              onClick={onReject}
+            >
+              Reject
+            </button>
+          </div>
+        </footer>
+      </div>
+    </article>
+  );
+}
+
+function ScoreRow({
+  label,
+  value,
+  pct,
+  variant,
+}: {
+  label: string;
+  value: number;
+  pct: number;
+  variant?: "dim";
+}) {
+  return (
+    <div className="score">
+      <span className="score__label">{label}</span>
+      <span className={variant === "dim" ? "bar bar--dim" : "bar"}>
+        <span className="bar__fill" style={{ width: `${pct}%` }} />
+      </span>
+      <span className="score__value">{value.toFixed(2)}</span>
+    </div>
+  );
+}

package/src/components/memory-cache/CachedMemoryList.tsx

@@ -0,0 +1,47 @@
+import type { CachedMemory } from "@/stores/slices/memoryCacheSlice";
+import { percent } from "@/utils/format";
+
+type Props = {
+  memories: CachedMemory[];
+};
+
+export function CachedMemoryList({ memories }: Props) {
+  return (
+    <div className="list">
+      <div className="list__head">
+        <span>{memories.length} cached memories</span>
+        <span>top by retrieval score</span>
+      </div>
+      {memories.map((memory) => (
+        <div key={memory.id} className="list__row list__row--simple">
+          <div style={{ flex: 1, minWidth: 0 }}>
+            <div style={{ color: "var(--ink)", fontSize: 14.5, fontWeight: 500 }}>
+              {memory.summary}
+            </div>
+            <div className="meta">
+              <span>{memory.kind}</span>
+              <span className="meta__sep">·</span>
+              <span>
+                importance <ScoreBar value={memory.retrieval.importance} />{" "}
+                {memory.retrieval.importance.toFixed(2)}
+              </span>
+              <span className="meta__sep">·</span>
+              <span>
+                confidence <ScoreBar value={memory.evidence.confidence} dim />{" "}
+                {memory.evidence.confidence.toFixed(2)}
+              </span>
+            </div>
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function ScoreBar({ value, dim = false }: { value: number; dim?: boolean }) {
+  return (
+    <span className={dim ? "bar bar--dim" : "bar"}>
+      <span className="bar__fill" style={{ width: `${percent(value)}%` }} />
+    </span>
+  );
+}

package/src/components/memory-cache/EmptyCache.tsx

@@ -0,0 +1,13 @@
+type Props = {
+  loaded: boolean;
+};
+
+export function EmptyCache({ loaded }: Props) {
+  return (
+    <div className="tile">
+      <div className="body-dim">
+        {loaded ? "Cache is empty." : "No local cache loaded."}
+      </div>
+    </div>
+  );
+}

package/src/hooks/useCommitFlow.ts

@@ -0,0 +1,55 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { commitSelectedMemories } from "@/services/commitMemories";
+import { buildCommitPreview } from "@/services/signerApi";
+import type { CommitEntityKeys, CommitPreviewData } from "@/services/types";
+import { readError } from "@/utils/errors";
+
+export function useCommitFlow(selectedIds: string[]) {
+  const [preview, setPreview] = useState<CommitPreviewData | undefined>();
+  const [passphrase, setPassphrase] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | undefined>();
+  const [entityKeys, setEntityKeys] = useState<CommitEntityKeys | undefined>();
+
+  const loadPreview = useCallback(async () => {
+    setBusy(true);
+    setError(undefined);
+    try {
+      setPreview(await buildCommitPreview(selectedIds));
+    } catch (err) {
+      setError(readError(err, "Unable to build commit preview."));
+    } finally {
+      setBusy(false);
+    }
+  }, [selectedIds]);
+
+  const commit = useCallback(async () => {
+    if (!preview) return false;
+    setBusy(true);
+    setError(undefined);
+    try {
+      const keys = await commitSelectedMemories({ preview, passphrase, selectedIds });
+      setEntityKeys(keys);
+      return true;
+    } catch (err) {
+      setError(readError(err, "Commit failed."));
+      return false;
+    } finally {
+      setBusy(false);
+    }
+  }, [passphrase, preview, selectedIds]);
+
+  return {
+    preview,
+    passphrase,
+    busy,
+    error,
+    entityKeys,
+    canCommit: Boolean(preview && preview.memories.length > 0) && passphrase.length >= 8 && !busy,
+    setPassphrase,
+    loadPreview,
+    commit,
+  };
+}

package/src/hooks/useMemoryCache.ts

@@ -0,0 +1,44 @@
+"use client";
+
+import { useCallback } from "react";
+import { getMemoryCache } from "@/services/signerApi";
+import { appStore, useAppStore } from "@/stores/appStore";
+import { readError } from "@/utils/errors";
+
+export function useMemoryCache() {
+  const memoryCache = useAppStore((state) => state.memoryCache);
+
+  const load = useCallback(async () => {
+    const current = appStore.getState().memoryCache;
+    if (current.loading) return;
+
+    appStore.setState((state) => ({
+      memoryCache: { ...state.memoryCache, loading: true, error: undefined },
+    }));
+
+    try {
+      const packs = await getMemoryCache();
+      appStore.setState((state) => ({
+        memoryCache: {
+          ...state.memoryCache,
+          memories: packs.flatMap((pack) => pack.memories).slice(0, 8),
+          loaded: true,
+          loading: false,
+        },
+      }));
+    } catch (error) {
+      appStore.setState((state) => ({
+        memoryCache: {
+          ...state.memoryCache,
+          loading: false,
+          error: readError(error, "Unable to load cache."),
+        },
+      }));
+    }
+  }, []);
+
+  return {
+    ...memoryCache,
+    load,
+  };
+}

package/src/hooks/usePendingMemories.ts

@@ -0,0 +1,137 @@
+"use client";
+
+import { useCallback, useEffect, useMemo } from "react";
+import { normalizeMemoryScope } from "@recallkit/core/memory";
+import type { PendingMemoryCandidate } from "@recallkit/core/schemas";
+import {
+  deletePendingMemory,
+  getPendingMemories,
+  updatePendingMemory,
+} from "@/services/signerApi";
+import { appStore, useAppStore } from "@/stores/appStore";
+import { readError } from "@/utils/errors";
+
+export function usePendingMemories() {
+  const pendingMemory = useAppStore((state) => state.pendingMemory);
+  const selectedSet = useMemo(() => new Set(pendingMemory.selectedIds), [pendingMemory.selectedIds]);
+  const committableSelectedCount = useMemo(
+    () =>
+      pendingMemory.items.filter((item) =>
+        pendingMemory.selectedIds.includes(item.id) && isCommittableDraft(item),
+      ).length,
+    [pendingMemory.items, pendingMemory.selectedIds],
+  );
+
+  const refresh = useCallback(async (options: { force?: boolean } = {}) => {
+    if (appStore.getState().pendingMemory.refreshing) return;
+
+    appStore.setState((state) => ({
+      pendingMemory: { ...state.pendingMemory, refreshing: true, error: undefined },
+    }));
+
+    try {
+      const items = await getPendingMemories(options.force ? { force: true } : {});
+      const validIds = new Set(items.map((item) => item.id));
+      appStore.setState((state) => ({
+        pendingMemory: {
+          ...state.pendingMemory,
+          items,
+          selectedIds: state.pendingMemory.selectedIds.filter((id) => validIds.has(id)),
+          refreshing: false,
+          loaded: true,
+        },
+      }));
+    } catch (error) {
+      appStore.setState((state) => ({
+        pendingMemory: {
+          ...state.pendingMemory,
+          refreshing: false,
+          error: readError(error, "Unable to load pending memories."),
+        },
+      }));
+    }
+  }, []);
+
+  useEffect(() => {
+    if (pendingMemory.loaded || pendingMemory.refreshing) return;
+    void refresh();
+  }, [pendingMemory.loaded, pendingMemory.refreshing, refresh]);
+
+  const toggle = useCallback((id: string) => {
+    appStore.setState((state) => {
+      const candidate = state.pendingMemory.items.find((item) => item.id === id);
+      if (candidate && !isCommittableDraft(candidate)) return state;
+      const selectedIds = state.pendingMemory.selectedIds.includes(id)
+        ? state.pendingMemory.selectedIds.filter((selectedId) => selectedId !== id)
+        : [...state.pendingMemory.selectedIds, id];
+
+      return {
+        pendingMemory: { ...state.pendingMemory, selectedIds },
+      };
+    });
+  }, []);
+
+  const patchCandidate = useCallback((candidate: PendingMemoryCandidate) => {
+    appStore.setState((state) => ({
+      pendingMemory: {
+        ...state.pendingMemory,
+        items: state.pendingMemory.items.map((item) =>
+          item.id === candidate.id ? candidate : item,
+        ),
+      },
+    }));
+  }, []);
+
+  const save = useCallback(
+    async (candidate: PendingMemoryCandidate) => {
+      await updatePendingMemory(candidate);
+      await refresh({ force: true });
+    },
+    [refresh],
+  );
+
+  const approve = useCallback(
+    async (candidate: PendingMemoryCandidate) => {
+      await updatePendingMemory({ ...candidate, status: "approved" });
+      await refresh({ force: true });
+    },
+    [refresh],
+  );
+
+  const reject = useCallback(
+    async (id: string) => {
+      await deletePendingMemory(id);
+      await refresh({ force: true });
+    },
+    [refresh],
+  );
+
+  const clearSelection = useCallback(() => {
+    appStore.setState((state) => ({
+      pendingMemory: { ...state.pendingMemory, selectedIds: [] },
+    }));
+  }, []);
+
+  const sortedItems = useMemo(
+    () => [...pendingMemory.items].sort((a, b) => b.importance - a.importance),
+    [pendingMemory.items],
+  );
+
+  return {
+    ...pendingMemory,
+    selectedSet,
+    sortedItems,
+    committableSelectedCount,
+    refresh,
+    toggle,
+    patchCandidate,
+    save,
+    approve,
+    reject,
+    clearSelection,
+  };
+}
+
+function isCommittableDraft(candidate: PendingMemoryCandidate): boolean {
+  return candidate.status === "approved" && normalizeMemoryScope(candidate.scope).level !== "session";
+}