Skip to content

Seed Memories

Jump to bottom
Pedro Gomes Branquinho edited this page Feb 15, 2026 · 1 revision

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 (Opus 4.5): EXPENSIVE - Strategy, dispatch, reviews
Lings (Claude): MODERATE - Task planning, drone orchestration
Drones (OpenRouter): CHEAP - File mutations, 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:

;; 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:

;; 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

---
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:

;; 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:

;; 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.

Clone this wiki locally