flowstate-agents-knowledge-store Package Skill

Package: @epicdm/flowstate-agents-knowledge-store Repository: epic-flowstate-community Path: packages/flowstate-agents-knowledge-store Version: 1.0.7

Use this published Dojo skill as the package-level entrypoint. For detailed workflows, use the package-local skills listed below.

Primary Package Workflow

FlowState Agents Knowledge Store

Status: Active Purpose: Help agents use @epicdm/flowstate-agents-knowledge-store correctly instead of treating it as a generic semantic-search package. Scope: /Users/sthornock/code/epic/epic-flowstate-community/packages/flowstate-agents-knowledge-store Trigger: Agent memory storage, LLM prompt enrichment, coordinator memory workflows, package maintenance, or Redis-backed knowledge retrieval. Input: Redis connection details, package source/docs, intended namespace, knowledge item shape, and retrieval goal. Output: Correctly configured client usage, safe knowledge operations, and verified retrieval behavior.

Overview

This package stores typed KnowledgeItem JSON documents in Redis and exposes a TypeScript client. It is not a full hosted vector database. Text search scans Redis keys and filters in memory; semantic search works only when callers provide embeddings or an embedding.embedFn.

Use this package when an agent or service needs durable, namespaced knowledge such as directives, patterns, decisions, insights, errors, requirements, strategies, preferences, or lessons.

Route by Task

Minimum Happy Path

import {
  createKnowledgeStoreClient,
  KnowledgePriority,
  KnowledgeType,
} from '@epicdm/flowstate-agents-knowledge-store'

const client = createKnowledgeStoreClient({
  redis: { host: 'localhost', port: 6379 },
  trackAccess: true,
})

const connected = await client.isConnected()
if (!connected) throw new Error('Redis is not reachable')

const result = await client.create({
  type: KnowledgeType.DIRECTIVE,
  namespace: 'project_alpha',
  title: 'Use TypeScript strict mode',
  content: 'All packages should keep TypeScript strict mode enabled.',
  metadata: {
    source: 'architecture-review',
    priority: KnowledgePriority.HIGH,
    tags: ['typescript', 'standards'],
  },
})

if (!result.success || !result.data) {
  throw new Error(result.error ?? 'Knowledge create failed')
}

const context = await client.retrieve({
  query: 'typescript standards',
  namespace: 'project_alpha',
  limit: 5,
})

await client.disconnect()

Composition

This package is consumed by:

• packages/flowstate-agents-llm-client for pre-query knowledge enrichment via retrieve().
• packages/flowstate-coordinator for memory distillation, initiative context, roundtable memory, and voice/profile knowledge.

When changing behavior, inspect reverse references with:

rg -n "flowstate-agents-knowledge-store|KnowledgeStoreClient|KnowledgeType|retrieve\\(" /Users/sthornock/code/epic/epic-flowstate-community/packages

Important Pitfalls

• create, get, update, and delete return OperationResult; check success before reading data.
• retrieve, search, and semanticSearch degrade to empty results on errors.
• getStats throws on error.
• Namespace and tag validation currently allows only alphanumeric, dash, and underscore. Downstream code using values like agent:${id} or trace:${id} needs sanitization or a package fix.
• PACKAGE_INFO.version in src/constants.ts is currently drifted from package.json.

Verification

yarn workspace @epicdm/flowstate-agents-knowledge-store test
yarn workspace @epicdm/flowstate-agents-knowledge-store typecheck
yarn workspace @epicdm/flowstate-agents-knowledge-store build

Done When

• The right subskill has been used for the task.
• Redis connectivity and result handling are verified.
• Namespaces/tags are valid for the package validator.
• Downstream consumers are checked when public behavior changes.

Package Skill Inventory

Package Skill Inventory: @epicdm/flowstate-agents-knowledge-store

Package Context

Package path: /Users/sthornock/code/epic/epic-flowstate-community/packages/flowstate-agents-knowledge-store

@epicdm/flowstate-agents-knowledge-store@1.0.7 is a publishable TypeScript library for Redis-backed long-term agent knowledge. Its usable surface is centered on KnowledgeStoreClient, createKnowledgeStoreClient, typed knowledge item contracts, text retrieval, best-effort LLM context retrieval, semantic vector search with caller-provided embeddings, stats, TTL, and access tracking.

Existing .flowstate/dojo files are treated as generated prototypes. They list features but do not yet teach package operation.

Skill Map

Anti-Sprawl Decision

Seven skills is appropriate for this package because it has one main client with four distinct workflows, one dense contract surface, and one meaningful troubleshooting path. Batch operations, TTL, stats, access tracking, and constants are folded into workflow/reference skills rather than split into feature-sized skilllets.

Feature Coverage

Composition Model

Use the package orchestrator first when the task is broad. It routes setup to lifecycle, data mutation to CRUD, prompt enrichment to retrieval, vector search to semantic search, lookup work to contracts, and failures to troubleshooting.

This package composes with @epicdm/flowstate-agents-llm-client for pre-query context and @epicdm/flowstate-coordinator for memory, initiative, roundtable, and voice workflows.

Deferred Skills

Review Questions

• Should validation allow : in namespaces/tags, or should coordinator sanitize values like agent:${id} and trace:${id}?
• Should PACKAGE_INFO.version be removed or synchronized with package.json?
• Should root README be updated before Dojo publication?
• Should getStats throw while search/retrieve degrade, or should the error model be standardized?

Review Gate

Package Skills Review: @epicdm/flowstate-agents-knowledge-store

Verdict

Pass with fixes.

The test skillset is a strong replacement for the generated Dojo feature-list output. It teaches concrete package workflows, names entry points, shows code, explains verification, and records downstream contract risks. Before publishing to Dojo, rebuild .flowstate/dojo from these reviewed skills and decide how to handle the namespace/tag validation mismatch.

Findings

Coverage

Drift and Contract Risks

Dojo Publication Decision

Do not publish existing generated Dojo files. The reviewed local skills are eligible to be converted into Dojo skill content after flowstate-package-dojo-sync rebuilds manifests and validates them.

Follow-Up Work

• Rebuild package .flowstate/dojo files from reviewed local skills.
• Decide whether package validation or downstream coordinator values should change for colon-separated namespaces/tags.
• Update root README and package docs to match source behavior.
• Add tests for CRUD, validation, semantic search, stats, TTL, and downstream compatibility when implementation work is in scope.

Start with this skill to understand the package purpose, then use the package-local focused skills for specific workflows. Keep this Dojo version aligned with packages/flowstate-agents-knowledge-store/package.json. Do not treat generated feature lists as lessons; use workflow evidence from CODE-REVIEW.md, SKILL-INVENTORY.md, and REVIEW.md.