Zen

Source string Source string

1553/10000 · 1553

The string is read only.

English Actions
iTag & TMSU — the plaintext tag layer
> Part of the infinity **learn** shelf · written for understandability
> (teckids.org ethos: free software, hackable, plaintext-first, no magic).
> A curious teenager or self-learner should be able to read this and rebuild it.
>
> Sibling docs: [DEEPDIVE.md](DEEPDIVE.md) · [glossary](../GLOSSARY.md) ·
> [learning journey](itag-journey.html) · canonical record:
> `~/my/cal/2026/06/12/ITAG-DEEP-DIVE-2026-06-12.iorg`
What it is, in one paragraph
**TMSU** is a small command-line program that lets you stick *tags* (little
labels like `agents` or `holiday`) onto your files, and then ask questions like
"show me every file tagged both `agents` and `active`". It keeps those labels in
one plain local database file — **no server, no daemon, no cloud account**.
**iTag** was a thin, friendly layer Daniel built *on top of* TMSU: a single
command (`itag`) that searches your tags and suggests related ones, plus an
optional web/API skin, plus little "bridges" that fed tags from other sources
(photos, calendar, map markers) into the same tag store. The fancy parts were
retired on 2026-05-28 as over-engineering. **What's left is the part that
matters and the part you can fully understand: tag files with TMSU, export them
to JSON, search them from a CLI.** That plaintext core is the *lightweight
fallback* — it keeps working when the fancy graph and services are down.
If you've never tagged a file before: a tag is just a word you attach to a file so you can find it later by that word instead of by where it lives in folders. One file can have many tags. One tag can be on many files. (More terms in the [glossary](../GLOSSARY.md).)
Why plaintext — and why this matters
The whole reason this doc exists is a goal Daniel set: **revive iTag+TMSU as a hacky, plaintext, lightweight fallback that he fully understands.** Here's why that's worth doing.
**Understandable end to end.** The surviving core is two short shell scripts (`itag`, `tmsu-export.sh`) and one well-documented external tool (TMSU). You can read every line in an afternoon. There is no hidden state, no ORM, no microservice you have to trust.
**Hackable.** Want a new way to search? Add ten lines to a shell script. Want a new tag namespace? Just prefix your tags. Nothing stops you, and nothing has to be redeployed.
**It survives when fancy things break.** A knowledge graph, a database server, an HTTP API — these have many ways to fail (port down, schema migration, daemon crashed, disk full on the server). A tag database that's just a local file, queried by a local binary, has almost none of those failure modes. When the graph is down, **plaintext tags still answer.**
**No lock-in.** Your tags export to plain JSON. If TMSU vanished tomorrow you could read your tags with `cat` and `jq` and re-import them anywhere. The data outlives the tool.
This is the same instinct behind keeping notes in `.org`/`.md` text files instead of a proprietary app: **the simplest thing that works is the thing that keeps working.**
The big picture
Here's the whole shape of the system. The **bold survivors** are what runs today; the dimmed boxes were retired (kept here so the picture makes sense).
SOURCES TMSU STORE CONSUMERS
(where tags come from) (one local tag db) (what reads tags)

you, tagging files ─────┐
tmsu tag file ... │
│
(photos → ph: ) ··┐│ ┌───────────────────────┐ ┌──────────────────┐
(calendar → ev: ) ··┤├──────▶ │ TMSU 0.7.5 │ │ itag CLI │ ◀ SURVIVES
(map markers → loc:) ··┤│ write │ db: ~/my/.tmsu/db │──▶ │ ~/my/bin/itag │
[RETIRED 2026-05-28] ···┘│ tags │ root: ~/my │ │ search + related │
│ │ ~files / ~tag types │ └──────────────────┘
fips org tasks → fips: │ └───────────┬───────────┘
(bridge, dormant) │ │
│ │ tmsu files / tmsu tags
tmsu-export.sh ──────────┘ ▼
(daily 06:00 timer) ◀ SURVIVES ┌───────────────────────┐ ┌──────────────────┐
exports tags → JSON │ tmsu-export.sh │──▶ │ RAFIKI graph │
~/my/.sync/tmsu/*.json │ → JSON for sync │ │ tags as nodes │
└───────────────────────┘ │ + co-occurrence │
┌───────────────────────┐ └──────────────────┘
│ FastAPI :8765 + SPA │
│ [RETIRED 2026-05-28] │
└───────────────────────┘
Read it left to right: **sources** put tags into the **one TMSU store**; **consumers** read them back. The arrows that survive are: *you tagging files*, *the `itag` CLI reading them*, *the daily export to JSON*, and *RAFIKI importing that to its graph*. Everything else was scaffolding.
The full architecture, history, and what-was-deleted record lives in the [deep dive](DEEPDIVE.md) and the canonical `~/my/cal/2026/06/12/ITAG-DEEP-DIVE-2026-06-12.iorg`.
What you can do today
These are **real commands you can run right now** on Daniel's machine. The TMSU store is rooted at `~/my`, so most commands start with `cd ~/my`.
1. Tag a file
cd ~/my
tmsu tag notes/idea.md agents active draft
That attaches three tags (`agents`, `active`, `draft`) to `notes/idea.md`. You can add `key=value` tags too:
tmsu tag photo.jpg holiday country=france
2. Find files by tag
cd ~/my
tmsu files agents active # files with BOTH tags (implicit "and")
tmsu files "agents and not draft" # boolean query
tmsu files agents or research # either tag
`tmsu files` with no query lists every tagged file. Queries run against the database, so they're fast even over thousands of files.
3. List what tags exist
cd ~/my
tmsu tags # every tag in the store
tmsu tags notes/idea.md # just the tags on one file
4. Search across everything with the `itag` CLI
The `itag` command is the friendly front. It searches files (and, when present, photo/event/fips tag namespaces), then prints a dim line of **related tags** (tags that tend to appear alongside yours):

Loading…

User avatar None

String added in the repository

  1. infinity-learn
  2. docs
  3. English
SOURCES TMSU STORE CONSUMERS
(where tags come from) (one local tag db) (what reads tags)

you, tagging files ─────┐
tmsu tag file ... │
│
(photos → ph: ) ··┐│ ┌───────────────────────┐ ┌──────────────────┐
(calendar → ev: ) ··┤├──────▶ │ TMSU 0.7.5 │ │ itag CLI │ ◀ SURVIVES
(map markers → loc:) ··┤│ write │ db: ~/my/.tmsu/db │──▶ │ ~/my/bin/itag │
[RETIRED 2026-05-28] ···┘│ tags │ root: ~/my │ │ search + related │
│ │ ~files / ~tag types │ └──────────────────┘
fips org tasks → fips: │ └───────────┬───────────┘
(bridge, dormant) │ │
│ │ tmsu files / tmsu tags
tmsu-export.sh ──────────┘ ▼
(daily 06:00 timer) ◀ SURVIVES ┌───────────────────────┐ ┌──────────────────┐
exports tags → JSON │ tmsu-export.sh │──▶ │ RAFIKI graph │
~/my/.sync/tmsu/*.json │ → JSON for sync │ │ tags as nodes │
└───────────────────────┘ │ + co-occurrence │
┌───────────────────────┐ └──────────────────┘
│ FastAPI :8765 + SPA │
│ [RETIRED 2026-05-28] │
└───────────────────────┘
SOURCES TMSU STORE CONSUMERS
(where tags come from) (one local tag db) (what reads tags)

you, tagging files ─────┐
tmsu tag file ... │
│
(photos → ph: ) ··┐│ ┌───────────────────────┐ ┌──────────────────┐
(calendar → ev: ) ··┤├──────▶ │ TMSU 0.7.5 │ │ itag CLI │ ◀ SURVIVES
(map markers → loc:) ··┤│ write │ db: ~/my/.tmsu/db │──▶ │ ~/my/bin/itag │
[RETIRED 2026-05-28] ···┘│ tags │ root: ~/my │ │ search + related │
│ │ ~files / ~tag types │ └──────────────────┘
fips org tasks → fips: │ └───────────┬───────────┘
(bridge, dormant) │ │
│ │ tmsu files / tmsu tags
tmsu-export.sh ──────────┘ ▼
(daily 06:00 timer) ◀ SURVIVES ┌───────────────────────┐ ┌──────────────────┐
exports tags → JSON │ tmsu-export.sh │──▶ │ RAFIKI graph │
~/my/.sync/tmsu/*.json │ → JSON for sync │ │ tags as nodes │
└───────────────────────┘ │ + co-occurrence │
┌───────────────────────┐ └──────────────────┘
│ FastAPI :8765 + SPA │
│ [RETIRED 2026-05-28] │
└───────────────────────┘
a month ago
Browse all string changes

Things to check

Ellipsis

The string uses three dots (...) instead of an ellipsis character (…)

Reset

Glossary

English English
No related strings found in the glossary.

String information

Source string description
type: Fenced code block
Flags
no-wrap, read-only
Source string location
itag/OVERVIEW.md:71
String age
a month ago
Last updated
a month ago
Source string age
a month ago
Translation file
po/infinity-learn.pot, string 15