DEV Community

Marvin Ma
Marvin Ma

Posted on

I Built a Tool to Stop AI Coding Agents from Forgetting Everything Between Sessions

#ai #programming #productivity #opensource

The Problem: Every Session Starts from Zero

If you use AI coding agents, you've experienced this:

Session 1 (Copilot): "Build the auth module with OAuth support"
  → Great work. Deep debugging. Important decisions made.

Session 2 (Claude): "Can you continue the auth work?"
  → "What auth module? I don't see any context about OAuth."

Session 3 (Cursor): "We need to refactor the auth flow"
  → "Can you explain the project architecture first?"
Enter fullscreen mode Exit fullscreen mode

Every new session starts from zero. You re-explain the project. You repeat decisions. You waste tokens on context that should already be there.

It gets worse when you work in a team:

  • Your teammate's AI has zero knowledge of what you've built
  • Your product specs are in PDF/DOCX — AI can't read binary files
  • Requirements are scattered across Slack, docs, and meetings

I got tired of this and built fcontext.

What is fcontext?

fcontext is an open-source CLI tool that maintains a .fcontext/ directory in your project. Think of it as a shared brain that every AI agent reads at the start of each session.

pip install fcontext
Enter fullscreen mode Exit fullscreen mode

One command to set up:

cd your-project
fcontext init
fcontext enable copilot   # or: claude, cursor, trae
Enter fullscreen mode Exit fullscreen mode

That's it. Your AI agent now reads project context automatically.

How It Works

Here's what lives inside .fcontext/:

your-project/
  .fcontext/
    _README.md          # AI-maintained project summary
    _workspace.map      # Auto-generated project structure
    _cache/             # Binary docs converted to Markdown
    _topics/            # Session knowledge & conclusions
    _requirements/      # Stories, tasks, bugs
    _experiences/       # Imported team knowledge (read-only)
Enter fullscreen mode Exit fullscreen mode

Each AI agent gets instructions in its native config format:

Agent Config Location
GitHub Copilot .github/instructions/*.instructions.md
Claude Code .claude/rules/*.md
Cursor .cursor/rules/*.md
Trae .trae/rules/*.md

The instructions teach the agent to:

  1. Read _README.md first to understand the project
  2. Check _topics/ for prior session conclusions
  3. Check _cache/ before asking you about binary documents
  4. Use fcontext req commands for requirements
  5. Save important conclusions to _topics/ before the session ends

Feature 1: Cross-Session Memory

The biggest win. Your AI agent saves session knowledge to _topics/, and the next session picks it up:

# End of today's session — AI saves conclusions
# .fcontext/_topics/auth-debugging.md gets created automatically

# Tomorrow, new session:
# AI reads _topics/ → knows exactly what happened yesterday

# You can also check manually:
fcontext topic list
fcontext topic show auth-debugging
Enter fullscreen mode Exit fullscreen mode

Before fcontext: "Can you explain the project?"
After fcontext: "Yesterday we fixed the OAuth redirect. Ready to implement GitHub provider?"

Feature 2: Cross-Agent Portability

Switch between agents freely. They all read the same .fcontext/ data:

fcontext enable copilot
fcontext enable claude
fcontext enable cursor

# All three agents now share the same context
# Use Cursor for frontend, Claude for backend — no context loss
Enter fullscreen mode Exit fullscreen mode

No vendor lock-in. The context belongs to your project, not to any agent.

Feature 3: Binary Document Indexing

Your product specs are in PDF. Your contracts are in DOCX. Your data is in XLSX. AI agents can't read any of them.

fcontext index specs/product-requirements.pdf
fcontext index contracts/
fcontext index data/quarterly-report.xlsx
Enter fullscreen mode Exit fullscreen mode

fcontext converts them to Markdown and stores them in _cache/. Now any agent can read your documents.

Supported formats: PDF, DOCX, XLSX, PPTX, Keynote, EPUB.

Feature 4: Requirements Tracking

Stop losing requirements across Slack threads and meeting notes:

# Add requirements
fcontext req add "User authentication via OAuth" -t story
fcontext req add "Support Google provider" -t task --parent STORY-001

# Track progress
fcontext req set TASK-001 status in-progress
fcontext req set TASK-001 status done

# Visualize
fcontext req board    # Kanban view
fcontext req tree     # Hierarchy view
Enter fullscreen mode Exit fullscreen mode

Your AI reads _requirements/ and builds against tracked specs — not hallucinated assumptions.

Feature 5: Experience Packs — Team Knowledge Sharing

This is where it gets powerful for teams.

# Team lead: export accumulated project knowledge
fcontext export team-knowledge.zip

# New team member: import it
fcontext experience import team-knowledge.zip

# Their AI instantly knows:
# - Project architecture
# - Domain concepts
# - Coding conventions
# - Known pitfalls
fcontext experience list
Enter fullscreen mode Exit fullscreen mode

You can also share via git:

# Export to a git repo
fcontext export git@github.com:team/domain-knowledge.git

# Import in another project
fcontext experience import git@github.com:team/domain-knowledge.git

# Keep it updated
fcontext experience update
Enter fullscreen mode Exit fullscreen mode

Real-World Scenario

Here's a typical day with fcontext:

Morning — Open a new Claude session. Claude reads .fcontext/_README.md and _topics/. It knows what you did yesterday, what decisions were made, and what's next.

Midday — Product manager sends updated specs (PDF). You run fcontext index specs/v2.pdf. Claude immediately references the new requirements.

Afternoon — Switch to Cursor for frontend work. Cursor reads the same .fcontext/ — no re-explaining needed.

End of day — Claude saves today's conclusions to _topics/debugging-payment-flow.md. Tomorrow's session starts with full context.

Next week — New developer joins. They run fcontext experience import team-pack.zip. Their AI is instantly productive.

Technical Details

  • Python 3.9+, single pip install
  • 213 tests, CI on Python 3.9/3.12/3.13
  • Zero cloud dependency — all data in local .fcontext/ directory
  • Apache 2.0 license
  • Uses markitdown for document conversion
  • Plain Markdown and CSV files — no proprietary formats

Get Started 

# Install
pip install fcontext

# Set up in your project
cd your-project
fcontext init
fcontext enable copilot   # or: claude, cursor, trae, opencode, openclaw

# Index your documents
fcontext index docs/

# Start coding — your AI now has persistent context
Enter fullscreen mode Exit fullscreen mode

GitHub: github.com/lijma/agent-skill-fcontext
PyPI: pypi.org/project/fcontext
Docs: lijma.github.io/agent-skill-fcontext

I'd love to hear your feedback. Have you experienced the "context amnesia" problem? How do you currently handle context across AI sessions?

Drop a comment or open an issue — I'm actively developing this and every perspective helps.

Top comments (0)