tinker-agent 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable user-facing changes to Tinker are documented here. The project follo
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-07-27
+
+### Added
+
+- Add optional global Memory for the interactive TUI. When configured, Tinker
+  extracts durable facts from completed turns, stores them locally, and exposes
+  relevant memories to the agent through `MemorySearch`.
+- Add a read-only `/memory` browser for reviewing the memories stored in the
+  current global Memory database.
+- Show live elapsed time in the TUI footer while a turn is running.
+
+### Changed
+
+- Compact and retire context toward 30% input utilization instead of 60%, leaving
+  more headroom for continued work after automatic or manual maintenance.
+
+### Fixed
+
+- Let the Tinker Chrome MCP server exit promptly when its client closes stdin,
+  avoiding the shutdown timeout during ordinary CLI exit.
+
 ## [1.4.0] - 2026-07-24
 
 ### Added
@@ -63,7 +84,8 @@ All notable user-facing changes to Tinker are documented here. The project follo
 - First formal npm release under the `tinker-agent` package name with the `tinker`
   executable.
 
-[Unreleased]: https://github.com/ishowshao/tinker/compare/v1.4.0...HEAD
+[Unreleased]: https://github.com/ishowshao/tinker/compare/v1.5.0...HEAD
+[1.5.0]: https://github.com/ishowshao/tinker/releases/tag/v1.5.0
 [1.4.0]: https://github.com/ishowshao/tinker/releases/tag/v1.4.0
 [1.3.0]: https://github.com/ishowshao/tinker/releases/tag/v1.3.0
 [1.2.1]: https://github.com/ishowshao/tinker/releases/tag/v1.2.1

package/README.md

@@ -243,6 +243,59 @@ Image-capable profile example:
   }
 }
 ```
+
+The top-level `memory` object is optional. When present, every field below is required. It enables completed-turn extraction and `MemorySearch` only in the TUI; one-shot runs do not load memory.
+
+| Field | Required | Type / constraint | Secret | Description |
+| --- | --- | --- | --- | --- |
+| `profile` | Yes | Non-empty string | No | Existing model profile used for completed-turn atomic-memory extraction. |
+| `embedding` | Yes | Object | Yes | Single embedding profile for the global memory database. |
+
+`memory.embedding` fields:
+
+| Field | Required | Type / constraint | Secret | Description |
+| --- | --- | --- | --- | --- |
+| `name` | Yes | Non-empty string | No | Stable identity for the embedding space. |
+| `kind` | Yes | Literal `"openai-compatible"` | No | Embedding transport kind. |
+| `model` | Yes | Non-empty string | No | Embedding provider model name. |
+| `apiBase` | Yes | Non-empty string | No | OpenAI-compatible API base URL. |
+| `apiKey` | Yes | Non-empty string | Yes | Embedding provider credential. |
+| `dimensions` | Yes | Positive integer | No | Fixed vector dimensions for the global memory database. |
+
+Enabling memory sends completed-turn text (not image bytes) to `memory.profile`, and sends extracted candidates plus search queries to the embedding endpoint. Derived memories are stored in `~/.tinker/memory/memory.sqlite`; newly inserted memory text is appended to the private development log `~/.tinker/memory/extracted-memories.log`.
+
+Atomic-memory profile example:
+
+```json
+{
+  "default": "text",
+  "profiles": {
+    "text": {
+      "model": "example-text-model",
+      "apiBase": "https://api.example.com/v1",
+      "apiKey": "your-model-api-key",
+      "contextWindowTokens": 128000,
+      "maxSupportedOutputTokens": 8192,
+      "includeReasoningContent": false,
+      "stream": true,
+      "inputModalities": [
+        "text"
+      ]
+    }
+  },
+  "memory": {
+    "profile": "text",
+    "embedding": {
+      "name": "example-embedding-space",
+      "kind": "openai-compatible",
+      "model": "example-embedding-model",
+      "apiBase": "https://embeddings.example.com/v1",
+      "apiKey": "your-embedding-api-key",
+      "dimensions": 1024
+    }
+  }
+}
+```
 <!-- END GENERATED: MODEL PROFILE FIELDS -->
 
 You can also select profiles explicitly for the TUI or one-shot command:
@@ -282,6 +335,7 @@ complete fixed policy and persistence contract.
 | `/status` | Show session and context details |
 | `/skills` | Show available and active Agent Skills |
 | `/mcp` | Show MCP servers and runtime tools |
+| `/memory` | Browse stored global memories |
 | `/compact [retire]` | Swap tool output or retire a cold history prefix |
 | `/clear` | Start a new session and clear conversation |
 | `/fork` | Clone the current session |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tinker-agent",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "A personal coding agent with an interactive TUI and one-shot CLI.",
   "license": "Apache-2.0",
   "type": "module",
@@ -20,6 +20,7 @@
     "src/image",
     "src/instructions",
     "src/mcp",
+    "src/memory",
     "src/model",
     "src/observation",
     "src/session",
@@ -62,11 +63,14 @@
     "docs:check": "bun scripts/render-public-contract-docs.ts --check",
     "tinker": "bun src/cli/index.ts",
     "check": "bun run typecheck && bun run format:check && bun run lint && bun run docs:check && bun run test && bun run bench:smoke",
+    "check:fast": "bun run typecheck && bun run format:check && bun run lint && bun run test:fast",
     "format": "biome format --write .",
     "format:check": "biome format .",
     "lint": "eslint \"bin/**/*.js\" \"src/**/*.{ts,tsx}\" \"scripts/**/*.ts\" \"packages/**/*.ts\" --max-warnings=0",
     "lint:fix": "eslint \"bin/**/*.js\" \"src/**/*.{ts,tsx}\" \"scripts/**/*.ts\" \"packages/**/*.ts\" --fix",
     "test": "FORCE_COLOR=0 bun test",
+    "test:fast": "FORCE_COLOR=0 bun test --path-ignore-patterns='**/*pty*.test.ts' --path-ignore-patterns='**/native-host-integration.test.ts'",
+    "test:e2e": "FORCE_COLOR=0 bun test src/__tests__/cli-pty src/__tests__/pty-tui-harness packages/tinker-chrome/__tests__/native-host-integration",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {

package/src/agent/runtime-session.ts

@@ -13,6 +13,7 @@ import {
   runtimeIdFactory,
   type RuntimeIdFactory,
   type SessionId,
+  type TurnId,
 } from "../ids/runtime-id";
 import { loadMcpConfig } from "../mcp/mcp-config";
 import {
@@ -71,11 +72,13 @@ import {
   renderedMessageHash,
 } from "../context/compiled-context-hash";
 import { createDefaultTooling, type DefaultTooling } from "../tools/registry";
+import type { ToolExecutor } from "../tools/types";
 import type { Refiner } from "../tools/web-fetch/refiner";
 import type { ProjectInstructionManifest } from "../instructions/project-instructions";
 import {
   SessionStore,
   createSessionCompatibilityContract,
+  type CompletedTurnSnapshot,
   type SessionRecoveryResult,
   type StoredSkillActivation,
 } from "../session/session-store";
@@ -212,6 +215,25 @@ export type SkillsUpdateSummary = {
   readonly addedOverrideCount: number;
 };
 
+export type CompletedTurnHookInput = {
+  readonly workspaceRoot: string;
+  readonly sessionId: SessionId;
+  readonly turnId: TurnId;
+  readonly snapshot: CompletedTurnSnapshot;
+};
+
+export type CompletedTurnHookFailure = {
+  readonly workspaceRoot: string;
+  readonly sessionId: SessionId;
+  readonly turnId: TurnId;
+  readonly reason: "completed_turn_snapshot_failed" | "completed_turn_enqueue_failed";
+};
+
+export type CompletedTurnHook = {
+  enqueue(input: CompletedTurnHookInput): void;
+  recordFailure(input: CompletedTurnHookFailure): void;
+};
+
 type CommonRuntimeSessionInput = {
   workspaceRoot: string;
   modelName: string;
@@ -233,6 +255,8 @@ type CommonRuntimeSessionInput = {
       };
   webFetchRefiner?: Refiner;
   toolingConfig?: PublicToolingConfig;
+  memorySearch?: ToolExecutor;
+  completedTurnHook?: CompletedTurnHook;
 };
 
 type CreateNewRuntimeSessionInput = CommonRuntimeSessionInput & {
@@ -534,6 +558,9 @@ class DefaultRuntimeSession implements RuntimeSession {
         historyReader: store.historyReader(),
         webFetchRefiner: input.webFetchRefiner,
         toolingConfig: input.toolingConfig,
+        ...(input.memorySearch === undefined
+          ? {}
+          : { memorySearch: input.memorySearch }),
         ...(session.skillCatalog.skills.size === 0
           ? {}
           : {
@@ -1717,6 +1744,9 @@ class DefaultRuntimeSession implements RuntimeSession {
       await this.appendTerminalEvent(turn, result, projectedMessageCount);
       pendingLedgerTurn.finish(result);
       settled = true;
+      if (result.status === "completed") {
+        this.notifyCompletedTurn(turn);
+      }
       await this.settleClosedTurnSkills();
       if (result.status === "completed") {
         await this.performAutomaticContextMaintenance();
@@ -1764,6 +1794,55 @@ class DefaultRuntimeSession implements RuntimeSession {
     }
   }
 
+  private notifyCompletedTurn(turn: TurnIdentity): void {
+    const hook = this.input.completedTurnHook;
+    if (hook === undefined) {
+      return;
+    }
+    let snapshot: CompletedTurnSnapshot;
+    try {
+      snapshot = this.store.readCompletedTurnSnapshot(turn.turnId);
+    } catch {
+      this.recordCompletedTurnHookFailure(
+        hook,
+        turn.turnId,
+        "completed_turn_snapshot_failed",
+      );
+      return;
+    }
+    try {
+      hook.enqueue({
+        workspaceRoot: this.input.workspaceRoot,
+        sessionId: this.sessionId,
+        turnId: turn.turnId,
+        snapshot,
+      });
+    } catch {
+      this.recordCompletedTurnHookFailure(
+        hook,
+        turn.turnId,
+        "completed_turn_enqueue_failed",
+      );
+    }
+  }
+
+  private recordCompletedTurnHookFailure(
+    hook: CompletedTurnHook,
+    turnId: TurnId,
+    reason: CompletedTurnHookFailure["reason"],
+  ): void {
+    try {
+      hook.recordFailure({
+        workspaceRoot: this.input.workspaceRoot,
+        sessionId: this.sessionId,
+        turnId,
+        reason,
+      });
+    } catch {
+      // Optional completed-turn integrations never fault a committed turn.
+    }
+  }
+
   private async performAutomaticCompaction(
     qualificationId: string,
   ): Promise<ContextCompactionResult | undefined> {

package/src/cli/config.ts

@@ -16,6 +16,7 @@ import {
   type ModelTokenEstimatorProfile,
   unknownProfileError,
 } from "./model-profiles";
+import type { MemoryEmbeddingConfig } from "../memory/contracts";
 import {
   parsePublicEnvironment,
   type ParsedPublicEnvironment,
@@ -45,6 +46,12 @@ export type RunnerConfigSelection = {
 
 type RunnerConfigTemplate = Omit<RunnerConfig, "sessionId">;
 
+export type ResolvedMemoryConfig = {
+  readonly profile: ModelProfile;
+  readonly contextBudget: ModelContextBudget;
+  readonly embedding: MemoryEmbeddingConfig;
+};
+
 export type ResolvedPublicConfig =
   | {
       readonly mode: "env";
@@ -56,6 +63,7 @@ export type ResolvedPublicConfig =
       readonly tooling: PublicToolingConfig;
       readonly profiles: ModelProfiles;
       readonly templates: ReadonlyMap<string, RunnerConfigTemplate>;
+      readonly memory?: ResolvedMemoryConfig;
       readonly persistDefaultProfile: (profileName: string) => Promise<void>;
     };
 
@@ -85,11 +93,16 @@ export function createResolvedPublicConfig(
         runnerConfigTemplateFromProfile(environment, profile),
       ]),
     );
+    const memory =
+      profiles.memory === undefined
+        ? undefined
+        : resolveMemoryConfig(profiles, profiles.memory.profile);
     return Object.freeze({
       mode: "profile",
       tooling: environment.tooling,
       profiles,
       templates,
+      ...(memory === undefined ? {} : { memory }),
       persistDefaultProfile: (profileName: string) =>
         persistDefaultProfile(profileName, environment.modelsPath),
     });
@@ -105,6 +118,22 @@ export function createResolvedPublicConfig(
   });
 }
 
+function resolveMemoryConfig(
+  profiles: ModelProfiles,
+  profileName: string,
+): ResolvedMemoryConfig {
+  const profile = profiles.profiles.get(profileName);
+  if (profile === undefined || profiles.memory === undefined) {
+    throw unknownProfileError(profileName, profiles);
+  }
+  const contextProfile = profileToContextProfile(profile);
+  return Object.freeze({
+    profile,
+    contextBudget: deriveModelContextBudget(contextProfile),
+    embedding: profiles.memory.embedding,
+  });
+}
+
 export function deriveRunnerConfig(
   snapshot: ResolvedPublicConfig,
   selection: RunnerConfigSelection,

package/src/cli/model-profiles.ts

@@ -4,12 +4,15 @@ import {
   type ModelContextProfile,
 } from "../model/model-context-profile";
 import {
+  MEMORY_CONFIG_FIELDS,
+  MEMORY_EMBEDDING_FIELDS,
   MODEL_PROFILE_FIELDS,
   MODEL_PROFILES_DOCUMENT_FIELDS,
   MODEL_TOKEN_ESTIMATOR_FIELDS,
   type ModelTokenEstimatorKind,
   type ModelTokenEstimatorMaxRetries,
 } from "./public-config-contract";
+import type { MemoryEmbeddingConfig } from "../memory/contracts";
 
 export type ModelProfile = {
   readonly name: string;
@@ -38,6 +41,12 @@ export type ModelTokenEstimatorProfile = {
 export type ModelProfiles = {
   readonly defaultProfile: string;
   readonly profiles: ReadonlyMap<string, ModelProfile>;
+  readonly memory?: MemoryConfig;
+};
+
+export type MemoryConfig = {
+  readonly profile: string;
+  readonly embedding: MemoryEmbeddingConfig;
 };
 
 export async function loadModelProfiles(configPath: string): Promise<ModelProfiles> {
@@ -144,7 +153,15 @@ export function parseModelProfiles(raw: string, sourcePath: string): ModelProfil
     profiles.set(profileName, parseProfile(profileName, profileValue, sourcePath));
   }
 
-  return { defaultProfile, profiles };
+  const memory =
+    json.memory === undefined
+      ? undefined
+      : parseMemoryConfig(json.memory, profiles, sourcePath);
+  return Object.freeze({
+    defaultProfile,
+    profiles,
+    ...(memory === undefined ? {} : { memory }),
+  });
 }
 
 export function resolveModelProfile(
@@ -286,6 +303,56 @@ function parseProfile(
   });
 }
 
+function parseMemoryConfig(
+  value: unknown,
+  profiles: ReadonlyMap<string, ModelProfile>,
+  sourcePath: string,
+): MemoryConfig {
+  const where = `Model profiles ${sourcePath}: "memory"`;
+  if (!isRecord(value)) {
+    throw new Error(`${where} must be an object.`);
+  }
+  assertKnownKeys(
+    value,
+    MEMORY_CONFIG_FIELDS.map((field) => field.name),
+    where,
+  );
+  const profile = requireString(value.profile, `${where}.profile`);
+  if (!profiles.has(profile)) {
+    throw unknownProfileNamesError(profile, [...profiles.keys()]);
+  }
+  const embedding = parseMemoryEmbedding(value.embedding, `${where}.embedding`);
+  return Object.freeze({ profile, embedding });
+}
+
+function parseMemoryEmbedding(value: unknown, where: string): MemoryEmbeddingConfig {
+  if (!isRecord(value)) {
+    throw new Error(`${where} must be an object.`);
+  }
+  assertKnownKeys(
+    value,
+    MEMORY_EMBEDDING_FIELDS.map((field) => field.name),
+    where,
+  );
+  const name = requireString(value.name, `${where}.name`);
+  if (value.kind !== "openai-compatible") {
+    throw new Error(`${where}.kind must be "openai-compatible".`);
+  }
+  const model = requireString(value.model, `${where}.model`);
+  const apiBase = requireString(value.apiBase, `${where}.apiBase`);
+  requireHttpUrl(apiBase, `${where}.apiBase`);
+  const apiKey = requireString(value.apiKey, `${where}.apiKey`);
+  const dimensions = requirePositiveInteger(value.dimensions, `${where}.dimensions`);
+  return Object.freeze({
+    name,
+    kind: "openai-compatible",
+    model,
+    apiBase,
+    apiKey,
+    dimensions,
+  });
+}
+
 function parseInputModalities(
   value: unknown,
   name: string,
@@ -472,6 +539,22 @@ function requirePositiveInteger(value: unknown, name: string): number {
   return value;
 }
 
+function requireHttpUrl(value: string, name: string): void {
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error(`${name} must be a valid HTTP(S) URL.`);
+  }
+  if (
+    (parsed.protocol !== "http:" && parsed.protocol !== "https:") ||
+    parsed.username !== "" ||
+    parsed.password !== ""
+  ) {
+    throw new Error(`${name} must be a valid HTTP(S) URL.`);
+  }
+}
+
 function parseBoolean(value: unknown, name: string): boolean {
   if (typeof value === "boolean") {
     return value;

package/src/cli/public-config-contract.ts

@@ -376,9 +376,91 @@ export type ModelTokenEstimatorMaxRetries = Extract<
   { readonly name: "maxRetries" }
 >["literalValue"];
 
+export type MemoryConfigField = {
+  readonly name: "profile" | "embedding";
+  readonly valueKind: "non-empty-string" | "embedding-profile";
+  readonly required: true;
+  readonly secret: boolean;
+  readonly description: string;
+};
+
+export const MEMORY_CONFIG_FIELDS = Object.freeze([
+  Object.freeze({
+    name: "profile",
+    valueKind: "non-empty-string",
+    required: true,
+    secret: false,
+    description:
+      "Existing model profile used for completed-turn atomic-memory extraction.",
+  }),
+  Object.freeze({
+    name: "embedding",
+    valueKind: "embedding-profile",
+    required: true,
+    secret: true,
+    description: "Single embedding profile for the global memory database.",
+  }),
+] satisfies readonly MemoryConfigField[]);
+
+export type MemoryEmbeddingField = {
+  readonly name: "name" | "kind" | "model" | "apiBase" | "apiKey" | "dimensions";
+  readonly valueKind: "non-empty-string" | "positive-integer" | "literal-string";
+  readonly required: true;
+  readonly secret: boolean;
+  readonly literalValue?: "openai-compatible";
+  readonly description: string;
+};
+
+export const MEMORY_EMBEDDING_FIELDS = Object.freeze([
+  Object.freeze({
+    name: "name",
+    valueKind: "non-empty-string",
+    required: true,
+    secret: false,
+    description: "Stable identity for the embedding space.",
+  }),
+  Object.freeze({
+    name: "kind",
+    valueKind: "literal-string",
+    required: true,
+    secret: false,
+    literalValue: "openai-compatible",
+    description: "Embedding transport kind.",
+  }),
+  Object.freeze({
+    name: "model",
+    valueKind: "non-empty-string",
+    required: true,
+    secret: false,
+    description: "Embedding provider model name.",
+  }),
+  Object.freeze({
+    name: "apiBase",
+    valueKind: "non-empty-string",
+    required: true,
+    secret: false,
+    description: "OpenAI-compatible API base URL.",
+  }),
+  Object.freeze({
+    name: "apiKey",
+    valueKind: "non-empty-string",
+    required: true,
+    secret: true,
+    description: "Embedding provider credential.",
+  }),
+  Object.freeze({
+    name: "dimensions",
+    valueKind: "positive-integer",
+    required: true,
+    secret: false,
+    description: "Fixed vector dimensions for the global memory database.",
+  }),
+] satisfies readonly MemoryEmbeddingField[]);
+
 export const MODEL_PROFILES_DOCUMENT_FIELDS = Object.freeze([
   Object.freeze({ name: "default", valueKind: "non-empty-string" as const }),
   Object.freeze({ name: "profiles", valueKind: "profiles-map" as const }),
+  Object.freeze({ name: "memory", valueKind: "memory-config" as const }),
 ]);
 
 export type PublicToolingConfig = {

package/src/cli/runner-dependencies.ts

@@ -64,6 +64,14 @@ export function createModelClient(
     return new FakeModelClient(fakeMode, {
       model: config.modelName,
       contextBudget: config.contextBudget,
+      inputModalities: config.inputModalities,
+      ...(config.tokenEstimator === undefined
+        ? {}
+        : { tokenEstimator: config.tokenEstimator }),
+      ...(env.TINKER_TEST_FAKE_MODEL_REQUEST_LOG === undefined ||
+      env.TINKER_TEST_FAKE_MODEL_REQUEST_LOG === ""
+        ? {}
+        : { requestLogPath: env.TINKER_TEST_FAKE_MODEL_REQUEST_LOG }),
     });
   }
 

package/src/cli/tui-memory.ts

@@ -0,0 +1,67 @@
+import {
+  boundedMemoryError,
+  memoryErrorCode,
+  type MemoryPaths,
+} from "../memory/contracts";
+import { MemoryCoordinator } from "../memory/memory-coordinator";
+import { MemoryLog } from "../memory/memory-log";
+import { resolveMemoryPaths } from "../memory/memory-store";
+import type { ResolvedMemoryConfig } from "./config";
+import { createModelClient } from "./runner-dependencies";
+
+export type TuiMemoryInitialization = {
+  readonly coordinator?: MemoryCoordinator;
+  readonly notice?: string;
+};
+
+export async function initializeTuiMemory(input: {
+  readonly config?: ResolvedMemoryConfig;
+  readonly env: NodeJS.ProcessEnv;
+  readonly paths?: MemoryPaths;
+  readonly createCoordinator?: typeof MemoryCoordinator.create;
+}): Promise<TuiMemoryInitialization> {
+  if (input.config === undefined) {
+    return Object.freeze({});
+  }
+
+  const paths = input.paths ?? resolveMemoryPaths();
+  const log = new MemoryLog(paths.log);
+  try {
+    const memoryConfig = input.config;
+    const coordinator = await (input.createCoordinator ?? MemoryCoordinator.create)({
+      paths,
+      embedding: memoryConfig.embedding,
+      extractionContextBudget: memoryConfig.contextBudget,
+      createExtractionClient: () => {
+        const profile = memoryConfig.profile;
+        return createModelClient(
+          {
+            modelName: profile.model,
+            apiKey: profile.apiKey,
+            apiBase: profile.apiBase,
+            includeReasoningContent: profile.includeReasoningContent,
+            stream: profile.stream,
+            contextBudget: memoryConfig.contextBudget,
+            inputModalities: profile.inputModalities,
+            ...(profile.tokenEstimator === undefined
+              ? {}
+              : { tokenEstimator: profile.tokenEstimator }),
+          },
+          input.env,
+        );
+      },
+    });
+    return Object.freeze({ coordinator });
+  } catch (error) {
+    const reason = memoryErrorCode(error, "memory_init_failed");
+    await log.append({
+      at: new Date().toISOString(),
+      kind: "init",
+      outcome: "failed",
+      reason,
+    });
+    return Object.freeze({
+      notice: `memory disabled: ${boundedMemoryError(error)}`,
+    });
+  }
+}