Class MemoryService

src/node/services/memoryService.ts:458–1099

// ---------------------------------------------------------------------------

export class MemoryService extends EventEmitter {
  /** Serializes mutating commands per physical root (agent tool + UI writes). */
  private readonly locks = new MutexMap<string>();
  constructor(
    private readonly config: Config,
    /** Host-local sidecar for pins + usage stats, recorded at this chokepoint. */
    private readonly metaService: MemoryMetaService
  ) {
    super();
  }

  // -------------------------------------------------------------------------
  // Usage stats (sidecar): recorded here — the single chokepoint every agent
  // command and UI write funnels through. UI reads (readFileWithSha) are
  // intentionally not counted: stats track agent usage, not human browsing.
  // Best-effort: stats failures must never break a memory command.
  // -------------------------------------------------------------------------

  /** Logical sidecar key, or null when the scope has no stable identity. */
  private logicalKeyFor(ctx: MemoryScopeContext, scope: MemoryScope, relPath: string) {
    if (scope === "project" && ctx.projectPath === "") return null;
    return memoryLogicalKey(scope, relPath, {
      projectPath: ctx.projectPath,
      workspaceId: ctx.workspaceId,
    });
  }

  private async recordUsage(
    ctx: MemoryScopeContext,
    scope: MemoryScope,
    relPath: string,
    options: { write: boolean }
  ): Promise<void> {
    try {
      const key = this.logicalKeyFor(ctx, scope, relPath);
      if (key === null) return;
      await this.metaService.recordAccess(key, options);
    } catch (error) {
      log.debug("[MemoryService] failed to record memory usage", { scope, relPath, error });
    }
  }

  private async recordRename(
    ctx: MemoryScopeContext,
    scope: MemoryScope,
    oldRelPath: string,
    newRelPath: string
  ): Promise<void> {
    try {
      const oldKey = this.logicalKeyFor(ctx, scope, oldRelPath);
      const newKey = this.logicalKeyFor(ctx, scope, newRelPath);
      if (oldKey === null || newKey === null) return;
      // Pins and stats follow the file; the rename itself counts as a use.
      await this.metaService.renameKeys(oldKey, newKey);
      await this.metaService.recordAccess(newKey, { write: true });
    } catch (error) {
      log.debug("[MemoryService] failed to move memory usage stats on rename", {
        scope,