# Seed Memories

Pre-packaged knowledge that bootstraps the hive memory system for new users.

## What are Seeds?

Seeds are **curated markdown files** containing foundational knowledge that every hive-mcp installation benefits from. They encode:

- **Conventions**: Best practices and architectural patterns
- **Decisions**: Key design choices and their rationale
- **Snippets**: Reusable code patterns

Seeds live in the `seeds/` directory as markdown files with YAML frontmatter. On import, they become regular memory entries in Chroma with `scope:global` visibility.

```
seeds/
├── conventions/
│   ├── architecture-over-llm-behavior.md
│   ├── micromanagement-anti-pattern.md
│   └── ...
├── decisions/
│   └── architecture-choice.md
└── snippets/
    └── common-patterns.md
```

## Why Seeds?

### Problem: Cold Start

Fresh hive-mcp installations start with empty memory. Agents must rediscover foundational knowledge through trial and error:

- Coordinator learns (again) not to poll ling buffers
- Lings forget to pass `directory` for scoping
- Token hierarchy gets violated repeatedly

### Solution: Bootstrap with Seeds

Seeds provide **institutional knowledge** that new agents inherit immediately:

```
Without Seeds:           With Seeds:
Day 1: Discovery         Day 1: Productive
Day 2: Mistakes          Day 2: Advanced patterns
Day 3: Re-learning       Day 3: Project-specific work
Day 4: Finally useful
```

### Benefits

1. **Faster onboarding** - Agents start with best practices
2. **Consistency** - All projects share foundational knowledge
3. **Maintainability** - Update seeds, re-import, all agents benefit
4. **Community sharing** - Seeds can be contributed upstream

## Included Seeds

hive-mcp ships with 7 foundational convention seeds:

### 1. Architecture Over LLM Behavior

**File**: `seeds/conventions/architecture-over-llm-behavior.md`

**Core principle**: Never rely on LLMs following correct behavior consistently. Build systems that make wrong behavior impossible.

| Bad (LLM-dependent) | Good (Architecture-enforced) |
|---------------------|------------------------------|
| "Always pass agent_id" | Auto-inject from env var |
| "Remember to shout" | Require shout for completion |
| "Use directory param" | Extract project from context |

### 2. Micromanagement Anti-Pattern

**File**: `seeds/conventions/micromanagement-anti-pattern.md`

**The rule**: NEVER poll ling buffers (`get_buffer_content`) to check what they're doing.

Use proper channels instead:
- `hivemind_shout` for status updates
- `swarm_status` for structured state
- `swarm_collect` for task results

### 3. Project Scoping + Memory Pollination

**File**: `seeds/conventions/project-scoping-memory-pollination.md`

**Fundamental invariant**: All hive-mcp subsystems are project-scoped. Cross-project knowledge transfer happens ONLY through memory pollination to global scope.

```
Project A          Project B
    |                  |
    +-- promote -->+<-- promote --+
                   |
            Global Scope
         (Pollination Layer)
```

### 4. Separate DataScript Connections

**File**: `seeds/conventions/separate-datascript-connections.md`

**Pattern**: Each DDD bounded context gets its own DataScript connection atom. Avoids coupling unrelated domains through shared schemas.

### 5. Agora Nash Equilibrium

**File**: `seeds/conventions/agora-nash-equilibrium.md`

**Consensus mechanism**: Dialogues reach consensus when Nash equilibrium is achieved - no participant would unilaterally change their position.

Turn signals: `:propose`, `:counter`, `:no-change`, `:approve`, `:defer`

### 6. Token-Tiered Hierarchy

**File**: `seeds/conventions/token-tiered-hierarchy.md`

**Budget mental model**:
```
Coordinator (premium model): EXPENSIVE - Strategy, dispatch, reviews
Lings (cheap agentic models, e.g. a ling-wave): CHEAP - Implementation, tests, grunt work
```

**Key rule**: Coordinator should NEVER read large files, grep codebases, or do implementation work.

### 7. Dependency Tree

**File**: `seeds/conventions/dependency-tree.md`

**Complete dependency structure** for running hive-mcp:
- Runtime: Java 17+, Clojure CLI, Babashka, Emacs daemon, Docker
- Infrastructure: Chroma, Ollama + nomic-embed-text
- Startup order and troubleshooting guide

## Importing Seeds

### Quick Start

For agents setting up a new user's hive-mcp:

```clojure
;; Preview what will be imported
(mcp__hive__seed_list {:directory "/path/to/hive-mcp"})

;; Dry run (no changes)
(mcp__hive__seed_import {:directory "/path/to/hive-mcp" :dry_run true})

;; Actually import
(mcp__hive__seed_import {:directory "/path/to/hive-mcp"})
```

### Tool Reference

#### `seed_list`

List available seeds without importing.

| Parameter | Type | Description |
|-----------|------|-------------|
| `directory` | string | Base directory containing `seeds/` folder (default: cwd) |

**Returns**: Count and metadata for each seed file.

#### `seed_import`

Import seeds as memory entries.

| Parameter | Type | Description |
|-----------|------|-------------|
| `directory` | string | Base directory containing `seeds/` folder (default: cwd) |
| `dry_run` | boolean | Preview without importing (default: false) |

**Returns**: Summary with imported/skipped/error counts and details.

### Behavior

1. **Deduplication**: Seeds with identical content or title are skipped automatically
2. **Tagging**: All seeds get `seed` tag and `seed-source:<path>` tag
3. **Scope**: Seeds are imported with `scope:global` visibility
4. **Duration**: Uses the `duration` from frontmatter (usually `permanent`)

### Automation

Agents can automate seed setup during `/catchup`:

```clojure
;; Check if seeds exist
(when-let [seeds (mcp__hive__seed_list {:directory cwd})]
  (when (and (pos? (:count seeds))
             (zero? (count-memory-with-tag "seed")))
    ;; Fresh install - import seeds
    (mcp__hive__seed_import {:directory cwd})))
```

## Creating Your Own Seeds

### File Format

```markdown
---
type: convention
tags: [architecture, scope:global]
duration: permanent
---

# Your Seed Title

Content in markdown format...

## Sections

Use headers, tables, code blocks freely.
```

### Frontmatter Fields

| Field | Required | Values | Description |
|-------|----------|--------|-------------|
| `type` | Yes | `convention`, `decision`, `snippet`, `note` | Memory entry type |
| `tags` | No | Array of strings | Categorization tags |
| `duration` | No | `ephemeral`, `short`, `medium`, `long`, `permanent` | TTL category |
| `title` | No | String | Overrides filename as title |
| `project-id` | No | String | Override scope (default: global) |

### Directory Structure

```
seeds/
├── conventions/     # Best practices, patterns
│   └── your-convention.md
├── decisions/       # Architecture decisions
│   └── your-decision.md
└── snippets/        # Code patterns
    └── your-snippet.md
```

### Quality Guidelines

Good seeds:
- **Actionable** - Clear rules, not vague advice
- **Atomic** - One concept per seed
- **Examples** - Show good/bad patterns
- **Context** - Explain why, not just what
- **Tested** - Actually used in production

## Contributing Seeds

### Process

1. **Create seed file** in appropriate `seeds/` subdirectory
2. **Test locally** with `seed_list` and `seed_import --dry-run`
3. **Submit PR** to hive-mcp repository
4. **Review** - maintainers check quality and applicability

### PR Checklist

- [ ] Frontmatter valid YAML with required fields
- [ ] Tags include `scope:global` for universal seeds
- [ ] Content follows quality guidelines
- [ ] No project-specific assumptions
- [ ] Examples tested with hive-mcp

### Scope Considerations

| Seed Type | Scope Tag | Audience |
|-----------|-----------|----------|
| Universal principle | `scope:global` | All hive-mcp users |
| Clojure-specific | `scope:global`, `clojure` | Clojure projects |
| Project template | `scope:project:X` | Specific project |

### Future: Seed Registry

Planned feature: Community seed registry where users can discover and import curated seed collections:

```clojure
;; Future API (not yet implemented)
(seed_registry_search "clojure")
(seed_registry_install "hive-community/clojure-best-practices")
```

---

## Agent Quick Reference

For agents bootstrapping a new hive-mcp installation:

```clojure
;; 1. Check for seeds directory
(mcp__hive__seed_list {:directory "/path/to/hive-mcp"})

;; 2. If seeds found, import them
(mcp__hive__seed_import {:directory "/path/to/hive-mcp"})

;; 3. Verify import
(mcp__hive__mcp_memory_query {:type "convention" :tags ["seed"]})
```

Seeds provide the institutional knowledge that makes agents effective from day one.