ASK KNOX
beta
LESSON 243

Building Agent Expertise

Static seed files plus dynamic Akashic memory, the boot and shutdown protocol, shared domain modules, and the @use directive pattern — the four components that give agents persistent, compounding expertise.

14 min read

The previous lesson established the problem: a stateless generalist agent forgets everything between sessions, accumulates nothing, and improves nothing. The solution is expertise infrastructure — a combination of curated static knowledge and dynamic memory that makes each session start smarter than the last.

This lesson builds that infrastructure in four parts: seed files, the Akashic memory system, the boot and shutdown protocol, and the @use directive pattern for shared domain modules.

Part 1: Seed Files — The Deliberate Foundation

A seed file is a markdown document that you write, curate, and check into version control. It contains the foundational knowledge an agent needs to operate effectively in its domain — not the dynamic stuff that changes every session, but the stable stuff that defines how the domain works.

For a coding agent, a seed file contains:

# Coding Agent — Domain Seed

## Codebase Architecture
- Backend: Python 3.12 + FastAPI, runs in Docker on Knox Mac Mini
- Frontend: Next.js 15 + TypeScript, deployed to Vercel
- Database: Supabase (PostgreSQL) — use RLS for all tables
- Cache: Redis on invictus-net Docker bridge, host `redis`

## Naming Conventions
- Files: lowercase-kebab-case everywhere
- Functions: snake_case (Python), camelCase (TypeScript)
- Constants: UPPER_SNAKE_CASE
- Test files: test_<module>.py or <module>.test.ts

## Critical Rules
- NEVER commit directly to main — always feature branch + PR
- 90% coverage floor — no exceptions
- No os.getenv() in routers — use config injection

## Known Patterns
- Auth: use supabase.auth.getUser() — never decode JWT manually
- Errors: raise HTTPException with structured detail, never bare strings
- Background tasks: launchd on Knox, NOT asyncio.create_task in FastAPI

For a trading agent, the seed file is different but equally deliberate:

# Trading Agent — Domain Seed

## Strategy Parameters
- Bot: Foresight (Polymarket prediction markets)
- Mode: conservative — default, never change without explicit instruction
- Stop-loss: bid < entry × 0.50 (50% stop)
- Position sizing: Kelly fraction × 0.25

## Critical Infrastructure
- Runs on: Tesseract (192.168.1.150)
- Wallet: 0x39A1525f1CeD5d4Ee334d6357758a0daf0F4e75b
- Token: USDC.e (0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174) — NOT native USDC
- Network: Polygon — never send to Ethereum mainnet

## Hard Rules
- NEVER modify position size above max_position_size config
- NEVER disable stop-loss logic for "just this trade"
- If trades.db.lock is stale: rm data/trades.db.lock — but verify first

The seed file is version-controlled. When the architecture changes, you update the seed file. The agent reads it on boot. This is the foundation — deliberate, human-curated, stable.

Part 2: Dynamic Memory with Akashic

Seed files cover what you know upfront. Akashic covers what the agent learns over time.

Akashic Records is a semantic memory system — a vector-indexed knowledge store with MCP tools that agents can call to store, query, and retrieve memories across sessions. The key insight is that it is not just a log. It is a searchable knowledge base that the agent uses to answer the question: "What do I know about this?"

The memory entry structure:

# Storing a discovery during a session
await mind_remember(
    content="The Polymarket CLOB API returns empty results when
             limit > 500. Use 500 as the max page size or paginate
             manually. Discovered 2026-03-15 during market scan.",
    category="trading",
    tags=["polymarket", "clob-api", "pagination", "gotcha"],
    type="episodic"
)

# Storing a decision
await mind_remember(
    content="Decision: Use USDC.e (0x2791...) not native USDC on Polygon.
             Rationale: Polymarket positions are denominated in USDC.e.
             Native USDC requires a bridge step that adds latency and
             a failure point. Decided 2026-02-20.",
    category="trading",
    tags=["usdc", "polygon", "architecture-decision"],
    type="semantic"
)

On boot, the agent queries its memory namespace before starting work:

# Boot context hydration
context = await mind_query(
    query="current portfolio status, recent decisions, open issues",
    namespace="trading-agent",
    limit=20
)

# Now the session starts with accumulated context
# instead of from zero

The difference between session 1 and session 50 is the size and quality of this memory store. After 50 sessions:

  • The agent knows every significant API gotcha in its domain
  • It has the history of every architecture decision and the rationale
  • It can surface "we tried this before and it failed because X" without being told
  • It applies learned preferences without re-explanation

Part 3: The Boot and Shutdown Protocol

Memory infrastructure only works if the agent actually uses it. That requires a deliberate protocol — a defined sequence of operations that happens at session start and session end.

The boot protocol:

async def agent_boot(agent_id: str, config: AgentConfig) -> SessionContext:
    """
    Run before the first task of any session.
    """
    # 1. Register with the orchestrator
    await orchestrator.register(
        agent_id=agent_id,
        capabilities=config.capabilities,
        model=config.model,
        status="initializing"
    )

    # 2. Load the seed file
    seed_knowledge = load_seed_file(config.seed_path)

    # 3. Hydrate dynamic context from memory
    recent_context = await mind_query(
        query="recent work, open issues, active decisions",
        namespace=agent_id,
        limit=15
    )

    # 4. Check for pending directives
    pending = await orchestrator.get_pending_directives(agent_id)

    # 5. Update status to ready
    await orchestrator.update_status(agent_id, "ready")

    return SessionContext(
        seed=seed_knowledge,
        memory=recent_context,
        pending=pending,
        session_start=datetime.utcnow()
    )

The shutdown protocol:

async def agent_shutdown(
    agent_id: str,
    session: SessionContext,
    reason: str = "normal"
) -> None:
    """
    Run at session end — always, even on error.
    """
    # 1. Flush session discoveries to memory
    for discovery in session.discoveries:
        await mind_remember(
            content=discovery.content,
            category=session.domain,
            tags=discovery.tags,
            type="episodic"
        )

    # 2. Write session summary
    await mind_remember(
        content=f"Session {session.session_id} summary: "
                f"{session.tasks_completed} tasks completed. "
                f"Key decisions: {session.key_decisions}. "
                f"Open items: {session.open_items}.",
        category=session.domain,
        tags=["session-summary"],
        type="episodic"
    )

    # 3. Release registration
    await orchestrator.deregister(
        agent_id=agent_id,
        reason=reason,
        session_id=session.session_id
    )

The shutdown hook runs even when the session ends unexpectedly. Use a try/finally block or a process signal handler to ensure it fires:

async def run_agent(agent_id: str, config: AgentConfig) -> None:
    session = None
    try:
        session = await agent_boot(agent_id, config)
        await process_tasks(session)
    except Exception as e:
        logger.error(f"Agent {agent_id} error: {e}")
        if session:
            session.record_error(e)
    finally:
        if session:
            await agent_shutdown(
                agent_id,
                session,
                reason="error" if session.had_error else "normal"
            )

Part 4: The @use Directive and Shared Domain Modules

As your agent fleet grows, you will encounter a coordination problem: multiple agents need to know the same things. The security rules that apply to all agents. The organizational hierarchy. The shared API conventions. The deployment topology.

You could copy this knowledge into every agent's seed file. The problem: when the topology changes, you update one file and forget three others. They drift out of sync. The coding agent knows the new Redis hostname; the content agent still has the old one; the trading agent has an intermediate wrong state.

The solution is shared domain modules with an @use directive.

Create shared modules that encode org-wide knowledge:

# modules/org-topology.md

## Service Locations
- MacBook Pro (dev): 100.94.7.32
- Knox Mac Mini (runtime): 100.91.193.23
- Tesseract (trading): 192.168.1.150 — local network only

## Service Assignments
- OpenClaw, Akashic, Mission Control → Knox
- Foresight, Shiva, Leverage, Hermes → Tesseract
- Apollo, content pipelines → Knox

## Deployment Rule
- Trading services → Tesseract (Polygon access, no VPN)
- Everything else → Knox

# modules/security-rules.md

## Hard Rules (all agents)
- No private keys in logs or memory
- No production database mutations without approval
- No force-push to main
- No --no-verify commits
- Confirm before any destructive action

In each agent's CLAUDE.md, reference these modules:

# Coding Agent CLAUDE.md

@use modules/org-topology.md
@use modules/security-rules.md
@use modules/git-workflow.md

## Coding-Specific Rules
[agent-specific content here]

The @use directive is processed at boot — the referenced module content is injected into the agent's context. When you update modules/org-topology.md, all agents that @use it get the update automatically on their next boot.

This is the difference between a fleet of agents that share an evolving understanding of the organization, and a collection of agents that each have their own stale copies of the truth.

def load_agent_context(claude_md_path: str, modules_dir: str) -> str:
    """
    Process @use directives in a CLAUDE.md file.
    Returns the fully-expanded context string.
    """
    with open(claude_md_path) as f:
        content = f.read()

    lines = content.split('\n')
    expanded = []

    for line in lines:
        if line.startswith('@use '):
            module_path = line[5:].strip()
            full_path = os.path.join(modules_dir, module_path)
            with open(full_path) as mf:
                expanded.append(f"\n## [Module: {module_path}]\n")
                expanded.append(mf.read())
                expanded.append("\n")
        else:
            expanded.append(line)

    return '\n'.join(expanded)

Putting It Together

An agent with expertise is one that:

  1. Starts every session with a curated seed file covering its domain
  2. Hydrates dynamic context from a persistent memory store before the first task
  3. Runs a boot protocol that registers it with the fleet and loads its accumulated knowledge
  4. Runs a shutdown protocol that flushes session discoveries to memory and releases its registration
  5. References shared domain modules rather than maintaining isolated copies

The practical result: an agent that on session one is merely competent, and on session fifty is genuinely expert — not because the model changed, but because the infrastructure accumulated.

Summary

  • Seed files are curated, version-controlled foundations covering stable domain knowledge
  • Dynamic memory stores (Akashic) capture what agents learn during operation
  • Boot protocols hydrate context before the first task; shutdown protocols flush discoveries after the last
  • The @use directive imports shared modules to prevent knowledge drift across a fleet
  • Expertise is not a model property — it is an infrastructure property

What's Next

With expertise built for individual agents, the next lesson designs how to assemble those specialists into a coordinated team — parallel vs sequential execution, file territory ownership, and the orchestrator pattern.