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 pattern

• references/cleanup-strategies.md

• Scratch file lifecycle management