shelfai

Category: Tools & Productivity | Uploader: noahbfreedman-cloud | Downloads: 0 | Version: v1.0（Latest）
Use this skill when the user wants to manage AI agent knowledge, organize agent configurations, or set up post-session learning systems. Triggers include: organizing agent skills or knowledge into a structured shelf, extracting insights from conversation transcripts, splitting monolithic agent config files into modular pieces, managing memory files, searching indexed knowledge, or diagnosing shelf health. Use ShelfAI whenever a user mentions managing agent context, chunking configs, learning from sessions, compacting memory, or organizing reusable agent knowledge pieces.
Changelog: Source: GitHub https://github.com/noahbfreedman-cloud/ShelfAI
Directory Structure

Current level: tree/main/skills/claude/
📄 SKILL.md 11.3 KB
SKILL.md

---
name: shelfai
description: "Use this skill when the user wants to manage AI agent knowledge, organize agent configurations, or set up post-session learning systems. Triggers include: organizing agent skills or knowledge into a structured shelf, extracting insights from conversation transcripts, splitting monolithic agent config files into modular pieces, managing memory files, searching indexed knowledge, or diagnosing shelf health. Use ShelfAI whenever a user mentions managing agent context, chunking configs, learning from sessions, compacting memory, or organizing reusable agent knowledge pieces."
---

# ShelfAI: Structured Agent Knowledge Management

## Overview

ShelfAI is a CLI tool and Python library for managing AI agent knowledge as a structured, retrieval-optimized collection of files. It organizes skills, knowledge, memory, and resources into a "shelf" — a directory with standard subdirectories and an automatically-generated index.

**Key capabilities:**
- Initialize shelves with standard directory structure
- Add files with automatic categorization (skills, knowledge, memory, resources)
- Generate retrieval-optimized abstracts for each file
- Extract learning insights from conversation transcripts
- Split monolithic agent configs into modular, reusable pieces
- Compact memory files by removing duplicates and archiving stale entries
- Search abstracts to find relevant knowledge
- Monitor shelf health (file count, sizes, staleness)
- Export a shelf as a single consolidated file

**When to use ShelfAI:**
- Organizing accumulated agent skills and knowledge into a structured system
- Setting up post-session learning loops to automatically extract and store insights
- Breaking apart large, monolithic agent configuration files into smaller, selectively-loadable pieces
- Managing growing memory/context files that accumulate stale or duplicate data
- Creating searchable, abstracted views of agent knowledge for retrieval

---

## Shelf Structure

A ShelfAI shelf is a directory with this standard structure:

```
shelf/
├── index.md              # Auto-generated registry (DON'T edit manually)
├── skills/               # Reusable skill definitions
│   └── *.md
├── knowledge/            # Domain knowledge, reference docs
│   └── *.md
├── memory/               # Context, learnings, patterns
│   └── *.md
└── resources/            # Tools, templates, utilities
    └── *.md
```

Each file is a Markdown document. The index.md is regenerated by ShelfAI and contains:
- File listings for each category
- Retrieval-optimized abstracts (generated from file content)
- Metadata (last modified, size, staleness indicators)

---

## CLI Commands

### Initialization and Setup

**Initialize a new shelf:**
```bash
shelfai init
```
Creates the shelf/ directory structure with all required subdirectories and an empty index.md.

**Add a file to the shelf:**
```bash
shelfai add <file> --category <category>
```
Copies the file into the appropriate directory. Valid categories: `skills`, `knowledge`, `memory`, `resources`.

Example:
```bash
shelfai add code_review_guidelines.md --category knowledge
```

### Building and Searching

**Build/rebuild the index:**
```bash
shelfai index
```
Scans all files in the shelf and generates:
- File listings for each category
- Abstracts (condensed, retrieval-optimized summaries)
- Metadata (modification time, file size, staleness)

Run this after adding new files or when you want to regenerate abstracts.

**Search the index:**
```bash
shelfai search <query>
```
Searches through abstracts to find relevant files. Returns matching files with their abstracts and relevance scores.

Example:
```bash
shelfai search "how to format code review"
```

### Status and Health

**Check shelf health:**
```bash
shelfai status
```
Displays:
- Total file count by category
- Total shelf size
- Most recently modified files
- Stale files (not updated recently)
- Memory file health (duplicate/redundant content)

### Post-Session Learning

**Extract learnings from a transcript:**
```bash
shelfai session <transcript>
```
Analyzes a conversation transcript and:
- Extracts key insights and learnings
- Identifies reusable patterns or techniques used
- Suggests new files to create or existing files to update
- Outputs recommendations to stdout (or saves with `--output`)

Example:
```bash
shelfai session chat_transcript.md --output learnings.md
```

This is useful after a long agent session to automatically capture what was learned and integrate it into the knowledge base.

### Compacting and Maintenance

**Compact memory files:**
```bash
shelfai compact
```
Processes all memory/ files to:
- Remove duplicate entries
- Archive stale data (older than configurable threshold, default 90 days)
- Consolidate redundant content
- Output a summary of changes

Useful for keeping memory files lean and queryable as they grow over time.

**Scan for chunking candidates:**
```bash
shelfai chunk-scan <directory>
```
Analyzes files in a directory to identify good candidates for chunking (monolithic files that could be split).

Looks for:
- Files larger than a threshold (configurable, default 500 lines)
- Clear section boundaries (headers, separators)
- Multiple distinct topics within one file

Example:
```bash
shelfai chunk-scan ./agent-configs/
```

**Chunk a large file:**
```bash
shelfai chunk <file> --output-dir <dir>
```
Splits a monolithic file into smaller, topically-organized pieces based on structure (headers, sections).

Each output file includes:
- Clear topic/section name
- Links back to original file (for context)
- Ready to add to the shelf

Example:
```bash
shelfai chunk agent_full_config.md --output-dir ./chunked/
# Creates: agent_full_config_1_overview.md, agent_full_config_2_tools.md, etc.
```

### Export

**Export shelf as single file:**
```bash
shelfai export
```
Generates a consolidated markdown file containing all shelf contents, suitable for:
- Backup/archival
- Sharing the entire knowledge base
- Loading into a different system

Output: `shelf_export_<timestamp>.md`

---

## Python API

For programmatic access, use the Shelf class:

```python
from shelfai import Shelf

# Initialize
shelf = Shelf("./shelf")

# Read the index (loads abstracts and metadata)
shelf.read_index()

# List all files in a category
files = shelf.list_files(category="skills")
# Returns: [{"name": "file.md", "abstract": "...", "size": 1024, "modified": "2024-..."}, ...]

# Read a file from the shelf
content = shelf.read_file("skills/code_review.md")

# Get shelf status
status = shelf.status()
# Returns: {"total_files": 15, "by_category": {...}, "total_size_bytes": 45000, ...}

# Search (returns list of matching files with abstracts)
results = shelf.search("code review patterns")

# Export shelf
shelf.export(output_path="shelf_backup.md")
```

---

## Best Practices

### Writing Good Abstracts

Abstracts are the primary discovery mechanism. When you rebuild the index, ShelfAI generates abstracts automatically, but:

- **Write clear file headers and summaries** — the first 100-200 words of each file become the basis for the abstract
- **Use descriptive section headers** — they help ShelfAI identify boundaries and topics
- **Avoid wall-of-text files** — if a file is hundreds of lines without clear structure, chunk it first

### File Organization

**skills/**: Reusable techniques, workflows, patterns. Example: `code_review_framework.md`, `debugging_strategy.md`.

**knowledge/**: Reference information, domain knowledge, documentation. Example: `python_best_practices.md`, `api_reference.md`.

**memory/**: Session notes, learnings, context from past interactions. Example: `conversation_learnings_2024_q1.md`, `client_preferences.md`.

**resources/**: Tools, templates, prompts. Example: `code_template.py`, `prompt_template.txt`.

### Maintenance Routine

1. After a significant session or batch of learning, run:
   ```bash
   shelfai session <transcript> --output learnings.md
   shelfai add learnings.md --category memory
   ```

2. Monthly (or as needed), compact memory:
   ```bash
   shelfai compact
   ```

3. Periodically rebuild the index to keep abstracts fresh:
   ```bash
   shelfai index
   ```

4. Use `shelfai status` to watch for growing stale files and decide when to archive/remove them.

### Chunking Monolithic Files

If you have a large agent configuration file:

1. Scan for candidates:
   ```bash
   shelfai chunk-scan ./configs/
   ```

2. Chunk the file:
   ```bash
   shelfai chunk agent_config.md --output-dir ./chunked/
   ```

3. Add the chunks to the shelf:
   ```bash
   shelfai add ./chunked/agent_config_*.md --category skills
   ```

4. The original monolithic file can be archived or deleted.

### Learning Loop Workflow

After each agent session:

1. Extract transcript (from logs or conversation history)
2. Run learning extraction:
   ```bash
   shelfai session session_transcript.md --output insights.md
   ```
3. Review the generated insights.md
4. Add useful files to the shelf:
   ```bash
   shelfai add insights.md --category memory
   ```
5. Rebuild index:
   ```bash
   shelfai index
   ```
6. Search to verify new knowledge is discoverable:
   ```bash
   shelfai search "key insight from session"
   ```

---

## Common Workflows

### Setting Up a New Agent Knowledge Base

```bash
# 1. Initialize
shelfai init

# 2. Add existing files
shelfai add existing_skills.md --category skills
shelfai add api_reference.md --category knowledge
shelfai add past_learnings.md --category memory

# 3. Rebuild index
shelfai index

# 4. Verify
shelfai status
shelfai search "some topic"
```

### Consolidating Agent Configs

```bash
# 1. Identify large files
shelfai chunk-scan ./configs/

# 2. Chunk a monolithic config
shelfai chunk full_agent_config.md --output-dir ./chunks/

# 3. Add chunks to shelf
shelfai add ./chunks/full_agent_config_*.md --category skills

# 4. Rebuild index
shelfai index
```

### Post-Session Learning Capture

```bash
# 1. After a session, extract the transcript and run
shelfai session transcript.md --output session_learnings.md

# 2. Review and add
shelfai add session_learnings.md --category memory

# 3. Compact memory to avoid duplication
shelfai compact

# 4. Rebuild and verify
shelfai index
shelfai search "specific insight"
```

### Monitoring Shelf Health

```bash
# Check overall status
shelfai status

# Look for stale files
shelfai status --show-stale

# Check memory file compaction opportunities
shelfai compact --dry-run  # See what would be compacted
```

---

## How ShelfAI Supports Agent Knowledge

**Problem:** Agents accumulate large amounts of knowledge and context. Monolithic configuration files become unwieldy, memory grows without bounds, and it's hard to retrieve specific pieces of knowledge on demand.

**ShelfAI's solution:**
1. **Structured organization** — Files go into standard categories, making it easy to navigate
2. **Retrieval-optimized abstracts** — Search/discovery via condensed summaries rather than full-text grep
3. **Post-session learning** — Automatically extract and integrate insights from conversations
4. **Modular configs** — Chunk large files so agents can selectively load only relevant pieces
5. **Memory compaction** — Keep memory lean by removing duplicates and archiving stale data
6. **Export capability** — Share or back up the entire knowledge base

Use ShelfAI when you want to turn accumulated agent context into a well-organized, discoverable, maintainable knowledge base.
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
shelfai

Directory Structure

SKILL.md

Report

Notice
