traveler/memory

Gremlin's long-term memory store. Every AI exchange, ingested document, calendar event, decision, and entity Gremlin knows about lives here as a versioned markdown file.

This repo is the human-readable half of the memory system. The machine-readable half lives in Qdrant. Both are written together at ingest time and kept in sync.

---

Structure

traveler/memory/
├── schema.yaml          ← canonical schema — read this before writing any ingest worker
├── README.md            ← this file
├── YYYY/MM/             ← individual memory records by date
├── daily/               ← AI session write-backs, one file per day, append-only
├── entities/            ← persistent entity records (people, systems, businesses)
└── indexes/             ← auto-generated indexes rebuilt weekly by n8n

---

Record Types

Type	What it captures
episodic	Something that happened — event, conversation, session, incident
semantic	Something that is known — decision, preference, standard, fact
reference	External artifact ingested — document, email, note, web clip
task	Actionable item extracted from any source
entity	Person, place, system, or thing with persistent attributes

---

Context Tags

Context	Scope
personal	Phil's personal life, home, health, interests
shared	Involves Cindy — always paired with entities: [cindy]
business	PNC Fish or other business context
homelab	NetGrimoire infrastructure, services, code

---

Key Rules

Never delete records. Set status: archived or status: superseded instead. Git history is the audit trail.

Always write MD before Qdrant. The file is the source of truth. Qdrant is the index.

Dedup by source_id. If a record for a given source_id already exists, create a new record with supersedes: <old-uuid> and set the old record to status: superseded.

Tag Cindy explicitly. Any record involving Cindy gets entities: [cindy] in frontmatter and context: shared. This ensures she surfaces correctly in morning briefing and query filtering.

Tag business explicitly. PNC Fish records get context: business and entities: [pnc]. Keeps personal and business retrieval cleanly separated.

---

Frontmatter Quick Reference

---
id: uuid-v4                          # required — generated at ingest
type: episodic                       # required — see types above
source: obsidian                     # required — origin system
context: homelab                     # required — personal|shared|homelab|business
date: 2026-06-05                     # required — date of original content
ingested_at: 2026-06-05T22:14:00Z   # required — when Gremlin processed this
summary: "One to three sentence summary of the record."
tags: [gremlin, proxy, architecture]
entities: [cindy]                    # optional — named entities present
source_id: "paperless-1847"          # optional — ID in source system
embedded_with: nomic-embed-text      # set by ingest worker
summarized_with: qwen2.5:14b         # set by ingest worker
embedding_version: 1                 # increment when re-embedded
---

Full schema with all optional fields and type-specific extensions: schema.yaml

---

Qdrant Collections

Collection	Source
obsidian_v1	Obsidian vault notes
paperless_v1	Paperless-ngx documents
nextcloud_v1	Nextcloud calendar + files
email_v1	MailCow / IMAP
forgejo_v1	Repo commits, stack configs, CI/CD decisions
immich_v1	Immich photo metadata
session_v1	AI session write-backs
manual_v1	Manually created records

Collections are versioned (_v1, _v2) so re-embedding with a better model populates a new collection alongside the existing one. Cutover is a config change in gremlin/config.yaml.

---

Daily Log

daily/YYYY-MM-DD.md is append-only. The write-back worker adds one entry per AI exchange:

## 22:14 — Proxy routing architecture decision

**Provider:** claude
**Context:** homelab

### What was asked
Discussed routing rules for gremlin-proxy and privacy controls.

### What was decided / produced
- @local prefix always routes to Ollama
- Routing rules live in gremlin/config.yaml
- Default provider: claude

### Open threads
- Need to build FastAPI proxy container

---

Entity Files

entities/<name>.md are updated in place rather than versioned by date. Gremlin updates these when new information about a persistent entity is learned.

Current entities: phil.md, cindy.md, pnc.md, gremlin.md

---

Related

• Local Intelligence Architecture — system overview
• gremlin/config.yaml — embedding model, summarization model, routing rules
• traveler/services/gremlin-proxy/ — proxy container source
• traveler/notes/ — Obsidian vault (ingested into this repo)