Overview

contox_save_session persists the current session's work into the project memory via the V2 ingest pipeline. The AI provides a summary and a list of structured changes, each categorized by type.

Important: This tool must only be called when the user explicitly asks to save (e.g., "save", "save session", "contox save"). It must never be called automatically or proactively. The user may be working on multiple tasks in parallel and needs to control when sessions are saved.

After saving, the tool also updates the CLAUDE.md file in the project root with a summary of the brain contents (fire-and-forget, non-blocking).

Parameters

Name	Type	Required	Default	Description
`summary`	string	Yes	—	Brief session summary (1-3 sentences) describing what was accomplished
`changes`	array	Yes	—	List of structured changes to save (see schema below)
`headCommitSha`	string	No	—	HEAD commit SHA at save time (from `contox_git_digest`). Tracks the save position for incremental digests

Changes array schema

Each item in the changes array has the following structure:

Field	Type	Required	Description
`category`	enum	Yes	One of: `architecture`, `conventions`, `implementation`, `decisions`, `bugs`, `todo`
`title`	string	Yes	Brief title (e.g., "Added auth middleware", "Fixed CSS z-index bug")
`content`	string	Yes	Detailed content in markdown. Include file paths, patterns, and key decisions

Available categories

Category	Description
`architecture`	Tech stack, architecture decisions, design patterns, project structure, infrastructure
`conventions`	Coding conventions, style rules, linter gotchas, naming patterns, team agreements
`implementation`	Features built, components created, APIs implemented, integrations added
`decisions`	Key decisions with rationale: why X over Y, trade-offs considered, constraints
`bugs`	Bugs found and how they were fixed, edge cases discovered, workarounds applied
`todo`	Pending tasks, known issues, planned improvements, tech debt to address

Return value

On success, returns:

Field	Description
`eventId`	Unique ID for the raw ingest event
`sessionId`	Session identifier for grouping saves

The response also notes that enrichment is deferred — the user must click "Generate Memory" in the dashboard to trigger the AI enrichment pipeline.

Usage examples

Saving after implementing a feature

User: Save this session

Claude calls: contox_save_session({
  summary: "Implemented user authentication with JWT tokens and protected route middleware.",
  changes: [
    {
      category: "implementation",
      title: "Added JWT authentication system",
      content: "Implemented JWT-based auth in `src/lib/auth.ts` with access/refresh token rotation. Protected routes use `withAuth` middleware in `src/middleware.ts`."
    },
    {
      category: "architecture",
      title: "Auth middleware pattern",
      content: "All `/dashboard/*` routes are protected by Next.js middleware. Public routes are explicitly whitelisted in `src/lib/auth-config.ts`."
    }
  ],
  headCommitSha: "a1b2c3d"
})

Saving a bug fix

Claude calls: contox_save_session({
  summary: "Fixed race condition in session refresh that caused intermittent 401 errors.",
  changes: [
    {
      category: "bugs",
      title: "Fixed session refresh race condition",
      content: "The refresh token endpoint was being called multiple times in parallel when multiple API requests failed simultaneously. Added a mutex lock in `src/lib/auth-client.ts` to serialize refresh attempts."
    }
  ]
})

Notes

Content within changes is appended to existing memory sub-contexts, never overwritten.
The headCommitSha parameter enables incremental git digests — when provided, the next call to contox_git_digest will start from this commit instead of re-reading the full history.
The session log sub-context is updated automatically with the session summary and timestamp.
Raw events are stored immediately. Enrichment (extracting structured knowledge) is a separate step triggered from the dashboard.

contox_get_memory

contox_list_contexts

On this page