Tapestry

Files-first personal claims memory for long-lived work with AI agents.

Obsidian vault = system of record.
Thin CLI + plugin = arm / seal / HITL.
Full agent power stays in a real terminal (e.g. Grok Build).
Paste is not the memory path.

Source-available. Free for personal, non-commercial use.
Commercial use needs a separate license. See LICENSE and NOTICE.

---

Why

Chat is a terrible system of record. Static notes go stale without clean supersession. An LLM wiki is great for how the world works — and the wrong place for “what is our current protocol right now?”

Tapestry is the middle layer:

C  LLM wiki          general mechanisms & entities
B  personal vault    long-form life notes
A  Tapestry          current claims, supersedes, packs   ← this repo
0  live agent        thinks and acts in a real terminal

Supersession over mutation. When reality changes, you land a new claim that supersedes the old one. History stays. Provenance stays. Partitions keep people and projects from contaminating each other.

---

Vocabulary

Term	Meaning	Disk
Yarn	Domain workspace (health, coding, …)	yarns/<id>/
Thread	Long-lived conversation line	yarns/<y>/threads/<id>/
fiber	One sitting / segment	…/fibers/<id>/
Claim	One durable fact or decision	…/claims/<id>.md
Surface	Generated view of current claims	…/surface.md
Pack	Budgeted reopen context	…/context-pack.md (thread-scoped only)
Partition	Isolation key (person / project)	on thread + claims
Arm	Bind session paths + skill	.tapestry/active.json
Knot	Seal fiber → HITL claims	CLI / plugin

---

Loop

1. Open a note under yarns/<yarn>/threads/<thread>/
2. Open Terminal (arm) (plugin) or npm run cli -- arm <yarn> <thread>
3. Work in your agent; the tapestry-session skill appends the fiber transcript
4. Propose Seal → approve claims (HITL)
5. Next arm loads the pack (instructions + current claims + surface + recent summaries)

Sealed transcripts are cold (audit only). Prefer claims + pack on reopen.

---

Install

Requirements

• Node.js 20+ (macOS: Homebrew node is fine)
• Obsidian (desktop)
• An agent CLI you already use in a terminal (this project does not reimplement the agent)

1. Clone + deps

git clone https://github.com/Coyote-git/tapestry-memory.git
cd tapestry-memory
npm install

2. Create a vault (empty memory SoT)

# copy the template, or create an empty Obsidian vault and drop these files in
cp -R vault-template ~/Documents/Tapestry
export TAPESTRY_VAULT="$HOME/Documents/Tapestry"

Open ~/Documents/Tapestry as an Obsidian vault.

3. Install the plugin

./scripts/install-plugin.sh

In Obsidian: enable community plugins → enable Tapestry Control.
Settings → set repo root to your clone path and Node path if needed.

4. Smoke test

export TAPESTRY_VAULT="$HOME/Documents/Tapestry"
npm test
npm run cli -- vault
npm run cli -- new-yarn --name "Coding" --id coding
npm run cli -- new-thread coding --title "Main" --partition main --id main
npm run cli -- arm coding main

Then open yarns/coding/threads/main/ in Obsidian and use Open Terminal (arm).

---

Repo layout

server/                 CLI + claims / fibers / arm / seal / pack
obsidian-plugin/        Tapestry Control (thin control plane)
skills/tapestry-session Agent write path B (append transcripts)
vault-template/         Empty vault SoT (AGENTS, PROTOCOL, sample yarn)
scripts/                install-plugin.sh

Never commit your real vault. Claims, transcripts, and packs are personal memory — keep them local (or private backup). This repo is the product code + empty schema.

---

CLI (highlights)

npm run cli -- help
npm run cli -- list
npm run cli -- new-yarn --name "Health" --id health --partition-class person --default person-a
npm run cli -- new-thread health --title "Main" --partition person-a
npm run cli -- arm health main
npm run cli -- knot health main
npm run cli -- pack health main
npm run cli -- rename-thread health main --title "Main line"

---

Claim keys (optional)

Domain NLP for claim identity (partition/subject/aspect) lives only in each yarn’s yarn.json → claimKeys.
Creating a yarn never injects markers. Lab-style example (ferritin, HCT, …): examples/claim-keys-labs.json.

---

License

PolyForm Noncommercial 1.0.0 — free for personal / non-commercial use.

Not OSI “open source.” Source is available to read, run, and adapt for permitted purposes.
Commercial use requires a separate written license.

See LICENSE and NOTICE.

---

Status

Early MVP (0.1.0). Core loop works: arm → transcript → knot/HITL → claims → pack.
More updates to come. Not a rebuild of your agent — it owns memory structure, not the model.

---

Inspiration

• Karpathy — LLM Wiki pattern (Layer C: agent-maintained general knowledge)
• Files-first memory; cold archive + hot bounded context

Tapestry is not an LLM wiki. It is personal state with supersession — complementary, not competing.