Overview

This guide collects proven practices for maintaining a high-quality project brain and getting the best results from Contox. These recommendations apply whether you are a solo developer or part of a team.

Name schema keys clearly

Schema keys define the hierarchy of your brain. Use clear, consistent naming:

Do:

root/architecture/auth
root/conventions/typescript
root/implementation/api/users
root/decisions/database-migration
root/bugs/auth-token-expiry

Avoid:

root/misc
root/stuff
root/temp
root/architecture/auth-and-also-some-other-things

Good schema keys make it easy to navigate the brain, filter items, and understand the project structure at a glance.

Save sessions regularly

Save your sessions at natural breakpoints rather than waiting until the end of a long work session:

• After completing a feature -- Save when a feature is functionally complete
• After fixing a bug -- Save with context about what caused the bug and how it was fixed
• After making a key decision -- Save the decision with its rationale while it is fresh
• Before switching tasks -- Save your current context before moving to something else

Frequent saves produce richer evidence for the enrichment pipeline.

Write meaningful session summaries

The session summary is the most important piece of evidence for enrichment. Be specific:

Good summary: "Implemented JWT refresh token rotation. Added a /api/auth/refresh endpoint that validates the current refresh token, generates a new access/refresh pair, and invalidates the old refresh token. Used a token family approach to detect reuse."

Poor summary: "worked on auth stuff"

The more specific your summary, the more accurate the extracted memory items will be.

Run scans after major changes

Use contox scan after significant structural changes to your project:

• Adding new routes or API endpoints
• Creating new component directories
• Adding or removing major dependencies
• Reorganizing the project structure
• Setting up new configuration (e.g., adding Tailwind, changing ESLint rules)

The scanner gives the AI an up-to-date map of your project.

Review hygiene suggestions

Run the hygiene agent regularly:

• Quick mode after each session -- Catches issues while they are fresh
• Weekly mode on a schedule -- Catches accumulated drift and duplicates

Always review the proposed actions before applying. Pay special attention to:

• Merge actions -- Verify the combined content makes sense
• Deprecation actions -- Confirm the item is truly outdated
• High-confidence actions -- These are usually safe to apply without deep review

Use context packs for focused work

When working on a specific feature or area, use context packs instead of the full brain:

contox_context_pack(
  task: "Implementing email notification system for team invites",
  scope: "relevant",
  tokenBudget: 6000
)

Context packs provide more relevant context in fewer tokens, leading to better AI responses.

Keep the brain curated

Treat your project brain like documentation that matters:

• Approve items promptly -- Review and approve enrichment results soon after they are generated
• Deprecate outdated items -- When a technology is replaced or a convention changes, deprecate the old items
• Edit for accuracy -- If an AI-extracted item is mostly right but has errors, edit it rather than leaving it or deleting it
• Organize schema keys -- Periodically review your brain hierarchy and reorganize if needed

Use descriptive change categories

When saving sessions, categorize changes accurately:

Accurate categorization helps the enrichment pipeline organize items correctly.

Team-specific practices

For teams using Contox:

• Agree on conventions -- Establish team conventions for session summaries, schema key naming, and save frequency
• Review together -- Periodically review the brain as a team to ensure accuracy
• Use project visibility wisely -- Make shared projects public, keep sensitive or personal projects private
• Coordinate enrichment -- Avoid triggering enrichment simultaneously on the same project to prevent race conditions

Next steps

• V2 Pipeline -- Understand the full event flow
• Hygiene Agent -- Automated brain maintenance
• Team Collaboration -- Working together effectively