Skip to main content

Codex + maenifold: Persistent Development Context

Never lose context between coding sessions. Your decisions, architecture, and progress persist in a living knowledge graph.

Prerequisites

  • Codex installed
  • Active development project
  • Basic understanding of project documentation

Graph-First Reset Protocol

Because Codex (and all agents) experience memory resets between sessions, maenifold provides a systematic recovery protocol:

  1. Sync → Ensure graph reflects latest markdown changes
  2. RecentActivity → Identify active sessions and recent documents
  3. SearchMemories → Find relevant knowledge using hybrid search
  4. BuildContext → Navigate concept relationships for full context

This protocol ensures every session starts with complete context from the knowledge graph, not from scratch.

Plan Mode

Discovery and planning

Start → Sync →
RecentActivity →
SearchMemories →
BuildContext/Visualize →
Read files → Create plan

Act Mode

Implementation and execution

Start → Resume session →
Execute work →
WriteMemory/EditMemory →
Sync → Update context →
Summarize results

These workflows are embedded in the swe.md agent instructions and automatically guide Codex through systematic development.

Setup

1. Install maenifold

npm install -g @ma-collective/maenifold

2. Configure Codex

Add to ~/.codex/config.toml:

[mcp_servers.maenifold]
type = "stdio"
command = "maenifold"
args = ["--mcp"]
startup_timeout_sec = 120
tool_timeout_sec = 600
env = { MAENIFOLD_ROOT = "~/maenifold" }

3. Optional: Add swe.md agent instructions

Copy agent instructions to ~/.codex/agents/swe.md for automatic graph-first protocol.

4. Verify installation

codex chat "List maenifold MCP tools"

Walkthrough Examples

Example 1: Day 1 - Starting New Feature

Scenario: You're starting work on a new authentication feature.

Codex Session:

"I'm starting work on JWT authentication. Write a project brief and initial architecture decisions to memory."

What maenifold Does:

  1. Creates memory://projects/myapp/projectbrief.md
    • Scope: JWT authentication feature
    • Stakeholders: Backend team
    • Constraints: Must support refresh tokens
  2. Creates memory://projects/myapp/systemPatterns.md
    • Architecture: JWT stored in httpOnly cookies
    • Security: HMAC SHA-256 signing
    • Refresh strategy: Sliding window pattern
  3. Creates memory://projects/myapp/activeContext.md
    • Current: Implementing token generation
    • Next: Add refresh token rotation
    • Blockers: Need to decide token expiry time

All files contain [[JWT]], [[authentication]], [[security]] WikiLinks.

Example 2: Day 2 - Resume Work

Scenario: You're back the next day. Codex memory is reset.

Codex Session:

"What was I working on yesterday? Show recent activity."

maenifold Response via RecentActivity:

Recent activity (last 24 hours):
1. memory://projects/myapp/activeContext.md (8 hours ago)
- Current: Implementing token generation
- Next: Add refresh token rotation
2. memory://projects/myapp/systemPatterns.md (8 hours ago)
- JWT architecture decisions documented
3. memory://thinking/session-1234567890.md (8 hours ago)
- Sequential thinking: Security considerations

Codex automatically:

  • Reads activeContext.md
  • Has full context of yesterday's decisions
  • Knows exactly where to continue
  • No need to re-explain the feature

Example 3: Multi-Day Feature Development

Day 1: Architecture & planning
  • Write projectbrief.md, systemPatterns.md
  • Document [[security-requirements]]
Day 2: Implementation starts
  • Update activeContext.md with progress
  • Write memories about [[implementation-challenges]]
  • Link to relevant [[code-patterns]]
Day 3: Testing & refinement
  • SearchMemories for [[security-requirements]]
  • Verify all requirements met
  • Update progress.md with completion status
Day 4: Code review prep
  • BuildContext around [[JWT]] concept
  • Generate summary of all related decisions
  • Create review checklist from memory
Result: Complete development history, every decision documented, full traceability from requirements to implementation.

Project Memory Structure

memory://
└── projects/
    └── myapp/
        ├── projectbrief.md        # Foundation: scope, stakeholders, constraints
        ├── productContext.md      # User needs, desired outcomes
        ├── systemPatterns.md      # Architecture, integrations, invariants
        ├── techContext.md         # Tooling, environment, dependencies
        ├── activeContext.md       # Current priorities, next steps, blockers
        └── progress.md            # Status log, milestone tracking

Common Pitfalls

⚠️
Forgetting to update activeContext: Update after each session or you'll lose "current state"
⚠️
Not using [[concepts]]: WikiLinks are how maenifold links knowledge—use liberally!
⚠️
Skipping Sync: Run Sync after writing memories so they're searchable
⚠️
Over-documenting: Focus on decisions and "why", not every code change
⚠️
Ignoring Graph-First Reset Protocol: Always start sessions with Sync → RecentActivity → SearchMemories to rebuild full context
⚠️
Reading files blindly: Use SearchMemories and BuildContext to navigate the graph, don't manually read every file
⚠️
Not tracking assumptions: Use Assumption Ledger for architectural decisions with uncertainty—link to activeContext/progress for traceability

Advanced Patterns

Pattern 1: Assumption Tracking

# When making architectural decisions with uncertainty
codex chat "We're assuming users want single sign-on. Track this assumption."

# maenifold creates assumption ledger entry
# Later, when assumption is validated/invalidated:
codex chat "Update assumption: SSO requirement confirmed by product team"

Pattern 2: Cross-Project Learning

# Reuse patterns from previous projects
codex chat "Search memories for [[authentication]] patterns across all projects"

# maenifold returns authentication approaches from ALL projects
# Codex suggests best practices based on past experience

Pattern 3: Team Knowledge Sharing

# Multiple developers sharing same MAENIFOLD_ROOT
export MAENIFOLD_ROOT="/shared/team-knowledge"

# Each developer's Codex writes to shared graph
# All team members benefit from collective knowledge
# Search finds insights from entire team's work

Next Steps