sheeki03 FewWord - Filesystem-Based Context Engineering
The filesystem provides a single interface for storing, retrieving, and updating effectively unlimited context. This addresses the fundamental constraint that context windows are limited while tasks often require more information.
Core insight: Files enable dynamic context discovery—pull relevant context on demand rather than carrying everything in the context window.
v1 Feature: Bash commands are automatically intercepted and their output is offloaded to files when large. You will see a pointer and preview instead of full output.
Directory Structure
project/
└── .fewword/ # All plugin data in one namespace
├── scratch/ # Ephemeral (auto-cleaned hourly)
│ ├── tool_outputs/ # Offloaded command outputs
│ └── subagents/ # Agent workspace files
├── memory/ # Persistent (survives cleanup)
│ ├── plans/ # Archived completed plans
│ ├── history/ # Archived sessions
│ ├── patterns/ # Discovered patterns
│ └── preferences.yaml # User preferences
├── index/ # Metadata tracking
│ ├── current_plan.yaml # THE canonical active plan
│ ├── tool_log.jsonl # Tool execution log
│ └── mcp_metadata.jsonl # MCP tool metadata
└── DISABLE_OFFLOAD # Create to disable auto-offloading
Escape Hatch
If automatic offloading causes issues:
- Create file:
touch .fewword/DISABLE_OFFLOAD - Or set env:
export FEWWORD_DISABLE=1
Automatic Behaviors (v1)
Bash Output Offloading
When you run a Bash command, the plugin automatically:
- Captures stdout+stderr to a file
- After completion, measures output size
- If small (<8KB): shows full output normally, deletes temp file
- If large: shows pointer + preview (first/last 10 lines)
- Preserves the original exit code
What you see for large output:
=== [FewWord: Output offloaded] ===
File: .fewword/scratch/tool_outputs/pytest_20250107_143022_a1b2c3d4.txt
Size: 45678 bytes, 1234 lines
Exit: 0
=== First 10 lines ===
...preview...
=== Last 10 lines ===
...preview...
=== Retrieval commands ===
Full: cat .fewword/scratch/tool_outputs/pytest_20250107_143022_a1b2c3d4.txt
Grep: grep 'pattern' .fewword/scratch/tool_outputs/pytest_20250107_143022_a1b2c3d4.txt
Skipped commands (v1 conservatively skips):
- Interactive: ssh, vim, less, top, watch, python, node, psql, etc.
- Already redirecting: commands with
>,2>,| tee,| less - Heredocs: commands containing
<< - Pipelines: commands containing
| - Trivial: very short commands
MCP Tool Handling
- All MCP tool calls are logged to
.fewword/index/mcp_metadata.jsonl - Write-like operations (create, update, delete, commit, push) are gated
- Pagination parameters are automatically clamped to prevent excessive results
Manual Patterns
Pattern 1: Plan Persistence
For long-horizon tasks, use the canonical active plan:
# .fewword/index/current_plan.yaml
objective: "Refactor authentication module"
status: in_progress
steps:
- id: 1
description: "Audit current auth endpoints"
status: completed
- id: 2
description: "Design new token validation"
status: in_progress
- id: 3
description: "Implement and test"
status: pending
- Plan survives context summarization
- Re-read at turn start or when losing track
- When completed, automatically archived to
memory/plans/
Pattern 2: Sub-Agent File Workspaces
Sub-agents write findings directly to filesystem instead of message passing:
.fewword/scratch/subagents/
├── research_agent/
│ ├── findings.md
│ └── sources.jsonl
├── code_agent/
│ ├── changes.md
│ └── test_results.txt
└── synthesis.md
Pattern 3: Chat History as File Reference
When context window fills:
- Write full history to
.fewword/memory/history/session_{id}.txt - Generate summary for new context window
- Include reference: "Full history in .fewword/memory/history/session_{id}.txt"
- Use grep to recover details lost in summarization
Search Techniques
| Tool | Use Case | Example |
|---|---|---|
ls / find |
Discover structure | find .fewword -name "*.txt" -mmin -30 |
grep |
Content search | grep -rn "error" .fewword/scratch/ |
head/tail |
Boundary reads | tail -100 .fewword/scratch/tool_outputs/log.txt |
sed -n |
Line ranges | sed -n '50,100p' file.txt |
References
For detailed implementation patterns, see:
references/implementation-patterns.md- Code examples for each patternreferences/cleanup-strategies.md- Scratch file lifecycle management