---
name: memex-zettelkasten
description: >
  Shared knowledge base using memex CLI (Zettelkasten atomic cards with bidirectional links).
  Use when: (1) starting a task — recall related knowledge, (2) finishing a task — capture
  non-obvious learnings, (3) asked to remember/note/record reusable technical knowledge,
  (4) checking knowledge graph health, (5) searching past decisions or gotchas.
  NOT for: personal preferences (use MEMORY.md), daily logs (use memory/*.md),
  or human-facing docs (use OC Wiki).
---

# Memex Zettelkasten — Shared Knowledge Base

Atomic cards with `[[bidirectional links]]` stored in `~/.memex/cards/`.
All agents share the same card store. Git sync available for cross-VM replication.

## Core Workflow

### Task Start → Recall

```bash
memex search "<keywords>"    # full-text search
memex read <slug>            # read specific card
memex links <slug>           # see related cards
```

Search before working. If relevant cards exist, read them to avoid repeating mistakes.

### Task End → Capture

Only write cards for **non-obvious** learnings. Skip if the knowledge is trivial or well-documented.

```bash
memex write <slug> << 'CARD'
---
title: "Short Noun Phrase ≤60 chars"
created: "YYYY-MM-DD"
source: "openclaw-<agent-name>"
tags: [tag1, tag2]
category: "<domain>"
---

One atomic insight per card. Use [[other-slug]] for bidirectional links.
CARD
```

### Required Frontmatter

| Field | Required | Format |
|-------|----------|--------|
| `title` | ✅ | Noun phrase, ≤60 chars |
| `created` | ✅ | ISO date `YYYY-MM-DD` |
| `source` | ✅ | `openclaw-<agent>` (e.g. `openclaw-xiaomo`) |
| `tags` | optional | YAML list |
| `category` | optional | Single string |
| `links` | optional | YAML list of slugs |

### Slug Rules

- **kebab-case**, all English, 3-60 chars
- Descriptive but concise: `docker-compose-port-binding`, not `note-1`

### Categories

`architecture` · `backend` · `frontend` · `devops` · `tooling` · `security` · `workflow`

### Tag Types

Domain: `docker`, `nodejs`, `api`, `azure`, `openclaw` …
Type: `decision`, `gotcha`, `pattern`, `howto`, `reference`, `debug`

### Special Slug Prefixes

| Prefix | Use |
|--------|-----|
| `adr-*` | Architecture decision records |
| `gotcha-*` | Pitfalls and traps |
| `pattern-*` | Reusable patterns / best practices |
| `tool-*` | Tool-specific tips |

## Graph Health Check

```bash
memex links          # overview: orphans, hubs, stats
memex archive <slug> # retire outdated cards
```

Run periodically (during heartbeat) to find orphaned cards and add links.

## What Goes Where

```
New knowledge →
  ├─ Only useful to me?        → MEMORY.md
  ├─ Reusable technical fact?  → memex card
  ├─ Human-facing document?    → OC Wiki
  └─ Temporary operational log → memory/YYYY-MM-DD.md
```

## Git Sync (Cross-VM)

```bash
memex sync --init <repo-url>   # first time: connect to shared repo
memex sync on                   # auto-push on every write
memex sync                      # manual pull + push
```