codexmemory

Documentation

Overview

Package codexmemory is a READ-ONLY diagnostic over an OpenAI Codex home (default ~/.codex). It reports the operator-visible MEMORY POSTURE of a guarded Codex session — whether memories are enabled, whether existing memories can be injected into future sessions, whether a new thread can become a memory input, whether external-context threads are excluded, and what generated state (including Chronicle screen-derived memories) is present on disk.

It is the trust-boundary counterpart to fak's own recall/durability gates: Codex memory changes what context a FUTURE Codex session may receive, so before launching `fak guard -- codex` an operator wants an explicit answer to "what is enabled, what can be written, what can be injected later, and where the generated state lives."

The package NEVER writes Codex state and NEVER prints raw memory contents — it inventories file counts, bytes, and top-level artifact names only. A missing or partial codex home is reported honestly ("not configured"), never a crash.

Posture keys (from the Codex config reference, current 2026-06-29):

• [features] memories — global enable
• memories.generate_memories — new threads may become inputs
• memories.use_memories — existing memories injected
• memories.disable_on_external_context — exclude MCP/web/tool threads
• memories.min_rate_limit_remaining_percent — rate-limit floor
• memories.extract_model / consolidation_model

See https://developers.openai.com/codex/memories and https://developers.openai.com/codex/config-reference.

Index

• Constants
• func Render(p Posture) string
• type DirInventory
• type Finding
• type Options
• type Posture
  • func Doctor(opts Options) Posture

Constants

const Schema = "fak.codexmemory.doctor.v1"

Schema is the stable schema tag carried in the JSON payload so the control-pane / TUI can route on a known shape.

Functions

func Render

func Render(p Posture) string

Render produces the compact, payload-free human view.

Types

type DirInventory

type DirInventory struct {
	Path   string `json:"path"`
	Exists bool   `json:"exists"`
	Files  int    `json:"files"`
	Bytes  int64  `json:"bytes"`
	Oldest string `json:"oldest,omitempty"` // RFC3339 mtime
	Newest string `json:"newest,omitempty"`
	// Artifacts lists top-level entry names only (never contents), sorted.
	Artifacts []string `json:"artifacts,omitempty"`
	// LargestBytes is the size of the single largest file (context-noise signal).
	LargestBytes int64 `json:"largest_bytes,omitempty"`
}

DirInventory is the safe, content-free summary of a memory directory.

type Finding

type Finding struct {
	Code    string `json:"code"`
	Message string `json:"message"`
	// Risk true ⇒ this finding should flip the advisory exit code nonzero.
	Risk bool `json:"risk"`
}

Finding is one operator-visible posture note.

type Options

type Options struct {
	// CodexHome, when non-empty, is used verbatim (the --codex-home flag).
	CodexHome string
	// RepoRoot, when non-empty, enables the AGENTS.md guidance-boundary check.
	RepoRoot string
	// Env overrides os.Getenv for tests (nil ⇒ the process environment).
	Env func(string) string
	// HomeDir overrides os.UserHomeDir for tests (nil ⇒ os.UserHomeDir).
	HomeDir func() (string, error)
}

Options configures a doctor run.

type Posture

type Posture struct {
	Schema    string `json:"schema"`
	CodexHome string `json:"codex_home"`
	// Source records how CodexHome was resolved: "flag", "env" (CODEX_HOME),
	// or "default" (~/.codex). Empty when the home could not be resolved.
	HomeSource string `json:"home_source"`

	ConfigPath   string `json:"config_path"`
	ConfigExists bool   `json:"config_exists"`

	// MemoriesEnabled is [features].memories. Absent ⇒ not configured.
	MemoriesEnabled triBool `json:"memories_enabled"`

	GenerateMemories         triBool `json:"generate_memories"`
	UseMemories              triBool `json:"use_memories"`
	DisableOnExternalContext triBool `json:"disable_on_external_context"`
	RateLimitFloor           *int    `json:"min_rate_limit_remaining_percent,omitempty"`
	RateLimitFloorSet        bool    `json:"min_rate_limit_remaining_percent_set"`
	ExtractModel             string  `json:"extract_model,omitempty"`
	ConsolidationModel       string  `json:"consolidation_model,omitempty"`

	// Memories inventories <home>/memories.
	Memories DirInventory `json:"memories"`
	// Chronicle inventories <home>/memories_extensions/chronicle (screen-derived).
	Chronicle DirInventory `json:"chronicle"`

	// Repo guidance boundary: when RepoRoot is set, report whether AGENTS.md
	// exists so the operator can confirm team invariants are checked in, not
	// stored only in user-local memories.
	RepoRoot     string `json:"repo_root,omitempty"`
	AgentsMD     bool   `json:"agents_md_present"`
	AgentsMDPath string `json:"agents_md_path,omitempty"`

	Findings []Finding `json:"findings"`
	// OK is true when no risky posture was found (no Finding with Risk true).
	OK bool `json:"ok"`
}

Posture is the read-only memory posture of a Codex home.

func Doctor

func Doctor(opts Options) Posture

Doctor reads a Codex home and returns its memory posture. It never writes and never returns an error for a missing/partial home — an unresolved or absent home is reported in the Posture itself.