sheeki03/few-word/fewword

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:

1. Captures stdout+stderr to a file
2. After completion, measures output size
3. If small (<8KB): shows full output normally, deletes temp file
4. If large: shows pointer + preview (first/last 10 lines)
5. 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:

1. Write full history to .fewword/memory/history/session_{id}.txt
2. Generate summary for new context window
3. Include reference: "Full history in .fewword/memory/history/session_{id}.txt"
4. Use grep to recover details lost in summarization

Search Techniques

References

For detailed implementation patterns, see:

• references/implementation-patterns.md - Code examples for each pattern
• references/cleanup-strategies.md - Scratch file lifecycle management