Configuration

codexfi works out of the box with sensible defaults. All settings are optional and can be customized via a JSONC config file.

Config file

The config file lives at ~/.codexfi/codexfi.jsonc. It is created automatically by the codexfi install command, or you can create it manually.

// Codexfi — plugin configuration
// Location: ~/.codexfi/codexfi.jsonc
{
  // ── API Keys ──────────────────────────────────────────────────────
  "voyageApiKey": "pa-...",
  "anthropicApiKey": "sk-ant-...",
  "xaiApiKey": "",
  "googleApiKey": "",

  // ── Extraction Provider ───────────────────────────────────────────
  // Which LLM to use for memory extraction: "anthropic" | "xai" | "google"
  "extractionProvider": "anthropic",

  // ── Plugin Settings ───────────────────────────────────────────────
  "similarityThreshold": 0.45,
  "maxMemories": 20,
  "maxProjectMemories": 20,
  "maxStructuredMemories": 30,
  "maxProfileItems": 5,
  "compactionThreshold": 0.80,
  "turnSummaryInterval": 5
}

API keys

At minimum, you need voyageApiKey plus one extraction provider key.

API keys must be set in codexfi.jsonc. The plugin does not read VOYAGE_API_KEY, ANTHROPIC_API_KEY, XAI_API_KEY, or GOOGLE_API_KEY environment variables. If a key is missing from the config file, the plugin will disable itself rather than silently fail.

When the plugin is disabled

If voyageApiKey is missing or codexfi.jsonc does not exist, the plugin disables itself and injects a [MEMORY - DISABLED] notice into the system prompt. The AI will proactively tell you what is wrong before responding to anything else:

[MEMORY - DISABLED]
The codexfi memory plugin is installed but not configured.
Run `bunx codexfi install` to set up your API keys and enable memory.

To fix this, run bunx codexfi install or manually add your keys to ~/.codexfi/codexfi.jsonc. Run bunx codexfi status to confirm the plugin is ready.

Extraction provider

Set the extraction provider in codexfi.jsonc:

{
  "extractionProvider": "anthropic"  // "anthropic" | "xai" | "google"
}

You can also set the provider during codexfi install (interactive prompt or --provider flag). The EXTRACTION_PROVIDER environment variable can be used as an override for CI/testing.

Resolution order: env var > config file > default ("anthropic").

The plugin falls back through all configured providers automatically. If the primary fails, it tries the next one in the fallback order: anthropic > xai > google.

Plugin settings

similarityThreshold

• Default: 0.45
• Range: 0.0 to 1.0

Minimum cosine similarity score for a memory to appear in search results. Lower values return more results (potentially less relevant); higher values are stricter.

maxMemories

• Default: 20

Maximum number of memories retrieved per scope (user or project) during semantic search.

maxProjectMemories

• Default: 20

Maximum number of project-scoped memories retrieved during structured fetches.

maxStructuredMemories

• Default: 30

Maximum number of memories retrieved for structured sections (Project Brief, Architecture, Tech Context, etc.) in the [MEMORY] block.

maxProfileItems

• Default: 5

Maximum number of user preference items shown in the "User Preferences" section of the [MEMORY] block.

injectProfile

• Default: true

Whether to include the "User Preferences" section in the [MEMORY] block. Set to false to disable user-scoped preference injection.

compactionThreshold

• Default: 0.80
• Range: 0.01 to 1.0

Ratio of context window usage that triggers compaction handling. When the conversation exceeds this threshold, codexfi injects memories into the compaction context and flags a full refresh for the next turn.

turnSummaryInterval

• Default: 5

Number of assistant turns between automatic session summary saves. Every N turns, a session-summary memory is generated in addition to the regular per-turn extraction.

containerTagPrefix

• Default: "opencode"

Prefix used for generating deterministic user and project tags from git email and directory hash.

userContainerTag

• Default: auto-generated from git email

Override the user-scope tag. Useful for testing or shared environments.

projectContainerTag

• Default: auto-generated from directory hash

Override the project-scope tag. Useful for linking multiple directories to the same project memory.

keywordPatterns

• Default: built-in patterns (see below)

Additional regex patterns that trigger the "explicit save" nudge. When a user message matches any pattern, codexfi injects a message telling the LLM to use the memory tool.

Built-in patterns include: remember, memorize, save this, note this, keep in mind, don't forget, learn this, store this, record this, make a note, take note, jot down, commit to memory, never forget, always remember.

Custom patterns are appended to the built-in list:

{
  "keywordPatterns": ["bookmark this", "save for later"]
}

Data storage

All memory data is stored locally at ~/.codexfi/store/store.db — a SQLite database with WAL mode. No external dependencies, no server process, no cloud sync.

The WAL and SHM files are created automatically when the database is opened and cleaned up when the last connection closes. They enable concurrent reads from multiple agents without blocking.