/** * MemoryBackend — the memory capability contract shared by every deployment * mode. Two implementations exist: * * - memdir (`slz rcs one` / `slz rcs web`, composite mode): the host injects * an in-process backend over the CLI's memdir (file-based, per-project) * so the web UI and the agent read/write the same store with zero sync * delay. * - sqlite (standalone multi-user): constructed per-request by the * `/web/memory/*` routes over the multi-user store * (services/memory/sqliteBackend.ts) — same capability surface plus * team-memory permission/space management. * * The interface is host-agnostic (pure DTOs, no CLI types) so the RCS * package never imports CLI modules — the dependency direction is strictly * composite layer (CLI) → server. */ export type MemoryScope = 'personal' | 'team' /** Structured create input — mirrors src/memdir/service.ts CreateMemoryFileInput. * `teamId` is the SQLite-store multi-team discriminator (memdir has a * single implicit team subtree and ignores it). */ export interface MemoryCreateInput { scope: MemoryScope name: string description?: string type: 'user' | 'feedback' | 'project' | 'reference' content: string teamId?: string } export interface MemoryCreateResult { error: string | null /** memdir-relative path of the created file (set on success). */ path?: string } export interface MemoryFileMeta { /** Path relative to the memory dir (e.g. `feedback_bun.md`, `team/user_x.md`). * SQLite-store entries use the row id as the opaque path identity. */ path: string name: string description: string | null type: string | null layer?: string mtimeMs: number scope: MemoryScope /** * Confidence in [0,1]. Merged from the SQLite index (the authority — * initial gate value, access boosts, decay); falls back to frontmatter * (default 0.5) when the index has no row. UI filter facet. */ confidence?: number /** * Times this memory has been recalled by retrieval (from the SQLite * index). UI display + filter facet; 0 when not indexed. */ accessCount?: number /** * Project key of the owning memdir — set on cross-project aggregation * (`project='all'` or an explicit key). Absent for the current project's * default listing. */ project?: string /** * Whether the caller may edit/delete/promote this entry. Absent on memdir * listings (host UIs decide — typically current-project = yes); set * per-row by the SQLite backend from its permission checks. */ canManage?: boolean /** Owning team display name — SQLite multi-team listings only. */ teamName?: string } /** One scannable project memdir under the memory base's projects/ root. */ export interface MemoryProjectInfo { /** Directory name under projects/ (sanitized absolute path of the repo). */ key: string /** Last path segment — short display name (e.g. `csa`). */ shortName: string /** True when this is the host process's own project. */ isCurrent: boolean } export interface MemorySearchHit { path: string score: number confidence?: number mtimeMs: number } export interface MemoryMatchLine { /** 1-based line number; 0 = the filename itself matched. */ line: number text: string } /** Plain regex search over the listed memory files (find-a-file tool). */ export interface MemoryFileMatch { path: string name: string description: string | null type: string | null /** Memory layer (L0 working / L1 episodic / L2 semantic / L3 procedural). */ layer?: string scope: MemoryScope matches: MemoryMatchLine[] /** Owning project key — set on cross-project search results. */ project?: string /** Owning team display name — SQLite multi-team search results. */ teamName?: string } export interface MemoryAutomationStatus { prefetch: boolean extract: boolean autoDream: boolean mode: 'normal' | 'poor' | 'sa' } export interface MemoryGovernanceStatus { health: { totalMemories: number memoriesByType: Record memoriesByLayer: Record avgConfidence: number capacity: { total: number maxFiles: number utilizationPct: number tier: 'healthy' | 'warning' | 'critical' } } layers: { working: number episodic: number semantic: number procedural: number } alerts: string[] conflicts: string | null autoDreamSetting: boolean | undefined automation: MemoryAutomationStatus teamEnabled: boolean } export interface MemoryBackendStatus { /** Which backend serves /web/memory/* — memdir (composite) or sqlite (multi-user). */ mode: 'memdir' | 'sqlite' enabled: boolean memoryDir: string teamEnabled: boolean automation: MemoryAutomationStatus } /** * Project selector for cross-project operations. `undefined` targets the * host process's own project (the session's memdir — the default every * existing caller relies on). `'all'` aggregates every scannable project. * A concrete key targets that project (read-only outside the current one). */ export type MemoryProjectSelector = string | undefined export interface MemoryBackend { /** Which implementation this is — 'memdir' (composite host injection) or * 'sqlite' (multi-user store adapter). */ readonly mode: 'memdir' | 'sqlite' status(): Promise /** Enumerate scannable project memdirs (cross-project browsing facet). * Empty for the SQLite backend — multi-user mode has no project concept. */ listProjects(): Promise list( scope?: MemoryScope, project?: MemoryProjectSelector, ): Promise /** Read a memory file. `project` must be a known project key or undefined; * cross-project reads are the only multi-project operation (browse-only). */ read(path: string, project?: MemoryProjectSelector): Promise write(path: string, content: string): Promise<{ error: string | null }> delete(path: string): Promise<{ error: string | null }> /** Create a memory file from structured fields — synthesizes the * `_.md` path and standard frontmatter, then delegates to * write (which maintains the MEMORY.md index). */ create(input: MemoryCreateInput): Promise /** Promote a personal memory to the team subtree. Errors when team memory * is disabled. `teamId` targets a specific team in the SQLite multi-team * model (required there, ignored by memdir's single team subtree). */ promoteToTeam( path: string, teamId?: string, ): Promise<{ error: string | null }> /** Plain regex search over the listed memory files (every layer) with * per-line match context — the find-a-file tool. */ search( pattern: string, project?: MemoryProjectSelector, ): Promise /** Preview of the agent's own per-turn scored retrieval (smartRetrieve). * A governance/diagnostic tool, deliberately distinct from search(). */ recallTest(query: string, topK?: number): Promise governanceStatus(): Promise } let memoryBackend: MemoryBackend | null = null /** Inject (or clear) the in-process memory backend. Called by the composite * host (`slz rcs one`) after startRcsServer — or via RcsServerOptions. */ export function setMemoryBackend(backend: MemoryBackend | null): void { memoryBackend = backend } export function getMemoryBackend(): MemoryBackend | null { return memoryBackend }