Tigerfs

Using TigerFS

TigerFS mounts PostgreSQL databases as directories. You interact with data using Read, Write, Glob, and Grep -- no SQL needed. File-first mode gives you a transactional, shareable filesystem backed by a database. Data-first mode lets you explore and manipulate an existing database using file tools. Most work uses file-first.

Which Mode?

Each directory in a TigerFS mount is either file-first or data-first:

• File-first: Contains .md or .txt files. Read and write files normally. See files.md.
• Data-first: Contains .info/ directory. Access rows as files or directories. See data.md.

Directory Structure

mount/
├── notes/                  # File-first (markdown workspace)
│   ├── hello.md
│   ├── tutorials/          # Subdirectories: ls shows only real files; .history/<file>/ remains path-accessible
│   ├── .history/           # Versioned history (root level only)
│   ├── .log/               # Operation log (root level only; pipeline hidden from ls)
│   ├── .savepoint/         # Named bookmarks for undo (root level only)
│   └── .undo/              # Preview and apply undo operations (root level only)
├── snippets/               # File-first (plain text workspace)
│   └── bash-loop.txt
├── .tables/                # Backing tables in tigerfs schema
│   └── notes/              # Data-first access to notes backing table
├── users/                  # Data-first (standalone table)
│   ├── .info/
│   ├── .by/
│   └── 1/  2/  3/ ...
├── .info/                  # Mount-level metadata (user identity)
└── .build/                 # Create new workspaces

File-First

A transactional, shareable filesystem backed by a database. Multiple users and agents can read and write concurrently. Create workspaces with .build/:

Bash "echo 'markdown' > mount/.build/notes"
Bash "echo 'markdown,history' > mount/.build/notes"    # with versioned history
Bash "echo 'plaintext' > mount/.build/snippets"         # body-only, no frontmatter

See files.md for full details on schemas, column roles, directories, and history.

What you can build

Because the filesystem is transactional and shared, it can implement collaborative workflows. Follow the recipe exactly:

Safe Editing with Savepoints

Before making multiple or risky edits, always create a savepoint:

Bash "echo '{\"description\":\"Before investigating bug #42\"}' > mount/workspace/.savepoint/before-investigation.json"

When to create a savepoint: investigating a bug, debugging, refactoring, multi-file edits, or any uncertain operation.

When to undo: user asks to revert, agent realizes the approach isn't working, or changes were made to wrong files.

Before undoing: always preview first and get user confirmation. Undo is destructive.

Undo is undoable: undo operations are logged (type='undo'), so you can undo an undo. Create a savepoint before a major undo for extra safety -- if the result isn't what was expected, undo back to that savepoint.

Common Workflows

"Create a savepoint"

Bash "echo '{\"description\":\"<why>\"}' > mount/workspace/.savepoint/<name>.json"

"What changed since the savepoint?"

1. Read the summary: Read "mount/workspace/.undo/to-savepoint/<name>/.info/summary"
2. If <= 5 files affected: for each file, read its before and current state, summarize cumulative changes in English
3. If > 5 files: present the summary table (type, filename, user, timestamp)
4. If user wants raw diffs: Bash "cd mount/workspace && diff -ru .undo/to-savepoint/<name> . -x '.*'"

"What changed in this file?"

1. Get the file's stable UUID: Read "mount/workspace/<dir>/.history/<file>/.id" (for a root-level file: Read "mount/workspace/.history/<file>/.id")
2. Find recent edits: Read "mount/workspace/.log/.by/file_id/<uuid>/.last/5/.export/json"
3. For each entry, read before and after, compare them, summarize in English.
4. Present with log_ids so the user can pick one to undo. Note: a single logical edit by an agent may produce multiple log entries (see How agent writes appear in the log).

"Show me the diff"

• Savepoint: Bash "cd mount/workspace && diff -ru .undo/to-savepoint/<name> . -x '.*'"
• Single file: Bash "diff -u --color mount/workspace/.log/<id>/before mount/workspace/.log/<id>/after"

"Undo to the savepoint"

1. Read the summary: Read "mount/workspace/.undo/to-savepoint/<name>/.info/summary"
2. If <= 5 files: summarize cumulative changes per file in English
3. Present to user: "This will undo N changes: [summary]. Go ahead?"
4. Only if confirmed: Bash "touch mount/workspace/.undo/to-savepoint/<name>/.apply"

"Undo this one change"

1. Read the log entries around the change. If multiple entries belong to the same logical write (same file_id, adjacent timestamps), each must be undone — see How agent writes appear in the log.
2. Read the log entry summary: Read "mount/workspace/.undo/id/<log_id>/.info/summary"
3. Show the diff: Bash "diff -u --color mount/workspace/.log/<id>/before mount/workspace/.log/<id>/after"
4. Present to user: "This will revert [description]. Go ahead?"
5. Only if confirmed: Bash "touch mount/workspace/.undo/id/<log_id>/.apply". For a multi-entry group, apply each entry's undo (newest log_id first) (or touch .undo/to-id/<id-before-the-group>/.apply to reverse the whole group atomically).

How agent writes appear in the log

Different write methods produce different numbers of log entries:

• Atomic-rename writes (Claude's Write/Edit, many editors): the operation produces multiple adjacent log entries. Typically: a create of a temp file like <file>.tmp.<pid>.<hash>, then for an overwrite a delete of the existing target, then a rename of the temp to the final name. That's 2 entries for a new file, 3 for an overwrite. The create and rename share the temp file's file_id; the delete (when present) carries the original target's file_id.
• Direct writes (shell redirects like echo "..." > file, in-place editors): a single create (new file) or edit (existing file) log entry. No temp file, no rename.

To revert a logical operation, find its group of entries, then undo them:

1. Read the log newest-first: Read "mount/workspace/.log/.last/8/.export/json".
2. Anchor on the rename to your target filename -- its file_id is the new file. The paired create shares that same file_id (filename <basename>.tmp.<pid>.<hash>); the delete (overwrites only) is the adjacent entry with the target filename but a different file_id. Checks: create+rename share a file_id; count is 2 (new file) or 3 (overwrite). filename is not a .by/-indexed column, so don't filter by it -- to get the id without scanning, read .history/<file>/.id, then query .log/.by/file_id/<id>/.
3. Undo each entry touch .undo/id/<log_id>/.apply, newest first -- order is mandatory; each step sets up the next. Out of order is destructive: RPC struct is bad on the stale .tmp.*, or silent deletion of the live file.

Shortcut: when the group is the latest change, touch .undo/to-id/<id-just-before-it>/.apply reverses it atomically in order. Never revert by re-typing content with Write/Edit -- that adds another rename group and loses the audit trail.

For advanced cases (filtered undo, per-user undo, pipeline queries), construct paths directly from files.md. See recipes.md Recipes 1-3 for complete workflow patterns.

Data-First

Direct access to database rows as files and directories. Use when you need column-level access, index lookups, bulk export, or structured data processing.

Read "mount/users/.info/count"                          # Row count
Read "mount/users/1.json"                               # Row as JSON
Read "mount/users/1/email"                              # Single column
Glob "mount/users/.by/email/alice@example.com/*"        # Index lookup
Read "mount/users/.by/status/active/.export/json"       # Filtered export

Access Strategy by Table Size

Always check .info/count first to choose the right strategy.

See data.md for the full reference.

Quick Reference

Directory Scanning Safety

Virtual directory layout: .history/, .log/, .savepoint/, .undo/ only appear in ls at the workspace root level, not inside subdirectories. Subdirectories' ls shows only real files; .history/<file>/ and .history/<file>/.id remain path-accessible from subdirectories.

Pipeline capabilities (.by/, .filter/, .order/, .export/, etc.) behave differently depending on where they appear:

• Inside .log/ or .savepoint/: accessible by explicit path but hidden from ls (prevents recursive scanner blowup on exponential pipeline branching).
• At a file-first workspace root or in a workspace subdirectory: rejected with ErrInvalidPath and a hint pointing at mount/.tables/<workspace>/ — that's the entry point for data-first access to a workspace's backing table.
• On a standalone data-first table (e.g., mount/users/) or under mount/.tables/<workspace>/: fully accessible.

Never recursively scan these directories -- always use targeted access patterns from the Quick Reference above:

• .log/ -- pipeline capabilities hidden from listing, use .log/.last/10/.export/json
• .savepoint/ -- same as .log/, use explicit paths
• .history/ -- one entry per file version; grows with every edit
• .undo/ -- preview trees that mirror the affected file hierarchy
• .by/<column>/ -- lists every distinct value; each expands to filtered rows
• .filter/<column>/ -- same as .by/ with higher limit
• .export/ -- reading files triggers full table/query dumps
• .import/ -- write interface; scanning could trigger unintended operations

Safe to scan:

• Regular files and subdirectories in a workspace (e.g., Glob "mount/workspace/**/*.md")
• .info/ -- small, fixed set of metadata files

Anti-Patterns

Database Management

When asked to create, mount, fork, or manage a database or filesystem, see ops.md for tigerfs CLI commands.

Detailed References

• files.md -- File-first: workspaces with files and directories, and history
• data.md -- Data-first: row-as-file, row-as-directory, metadata, indexes, pipeline queries
• recipes.md -- Recipes: kanban boards, knowledge bases, session context, snippets, safe exploration, compare approaches, multi-agent undo
• ops.md -- Operations: mount, create, fork, status, unmount

Source: timescale/tigerfs — distributed by TomeVault.