# Telvokdev Librarian Librarian

> Librarian

- Skill: `tomevault-io/telvokdev-librarian-librarian` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/telvokdev-librarian-librarian`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/telvokdev-librarian-librarian/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/telvokdev-librarian-librarian

---


# Librarian

We build a library together. Every insight worth remembering goes here.

## Tools

- `brief(query)` - Search our library with semantic search. Use before planning or when something feels familiar.
- `record(insight, ...)` - Save knowledge immediately when we learn something. One insight per call.
- `adopt(path)` - Copy imported entry to local (make it ours)
- `mark_hit(path)` - Track when an entry helps. Higher hits = higher ranking.
- `import_memories(format, path)` - Import from other AI tools (jsonl, markdown, cursor, json, sqlite)
- `rebuild_index()` - Rebuild semantic search index for legacy entries

## Workflow

### Before Thinking
Call `brief({ query: "relevant topic" })` to check what we already know. Also use when an issue comes up again or feels like something we solved before.

### During Work
Call `record()` immediately when we:
- Solve a problem (before moving to the next thing)
- Make a decision (capture the reasoning NOW)
- Hit a gotcha or mistake (it WILL come up again)
- Learn something non-obvious (context dies fast)

Don't wait. Don't batch. One insight = one record call. Multiple recordings in one response is fine.

### After Brief Helps
Call `mark_hit({ path: "..." })` when an entry from brief actually helped. This makes it rank higher next time.

## What to Record

**Yes:**
- Hard-won solutions (the "aha" moments)
- Gotchas, mistakes, and workarounds
- Patterns that worked
- Decisions and their reasoning
- Non-obvious learnings

**No:**
- Generic docs (search exists)
- Temporary fixes
- Things likely to change next week

## Entry Format

```markdown
# Title

Brief description of what this captures.

## Context
When/why this matters.

## The Insight
The actual knowledge.

## Example (optional)
Code or concrete illustration.
```

## Quality Bar

**"I wish we knew this yesterday"**

Good: "Stripe retries webhooks but doesn't dedupe - always check idempotency key"

Not for Librarian: "Redis is a key-value store." (Just a fact, not wisdom.)

## Smart Ranking

Entries are ranked by:
- 60% semantic similarity to your query
- 25% recency (newer = higher)
- 15% hit count (more helpful = higher)

## Examples

### Searching before planning
```
brief({ query: "stripe webhooks" })
```

### Recording immediately
```
record({ insight: "Clock skew between services - add 30s buffer to token validation" })
```

### Rich recording
```
record({
  intent: "Setting up GitHub org for Telvok",
  insight: "GitHub org names are first-come-first-served regardless of domain ownership",
  context: "GitHub, npm, branding",
  reasoning: "We owned telvok.com but someone squatted telvok org years ago",
  example: "Had to use telvokdev instead of telvok"
})
```

### Marking what helped
```
mark_hit({ path: "local/stripe-webhooks-need-idempotency.md" })
```

### Importing from other tools
```
import_memories({ format: "jsonl", path: "~/.aim/memory.jsonl", source_name: "anthropic" })
import_memories({ format: "sqlite", path: "~/memory.db", source_name: "mcp-memory" })
```

## File Structure

```
.librarian/
├── local/        # Our entries (indexed for semantic search)
├── packages/     # Downloaded packages
└── index.json    # Semantic embeddings
```

## See Also

- **librarian-marketplace** - Buy, sell, and search books on Telvok
- **librarian-bounties** - Knowledge bounty system (create, claim, fulfill)
- **librarian-auth** - Authentication and account management

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/telvokdev) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->