Neotex Knowledge Integration

Overview

Neotex is an agent-first knowledge system for storing and retrieving organizational knowledge and assets. This skill integrates Claude Code with neotex via CLI commands.

Conversation Start: Auto-Check

At conversation start, check if neotex is initialized:

ls .neotex/index.json 2>/dev/null

• If exists: Note available knowledge (scan summaries, don't fetch all)
• If missing but .neotex/ exists: Suggest neotex pull
• If no .neotex/: Skip neotex workflow unless user wants to initialize

When to Search

Search neotex when user asks about:

• Organizational conventions, standards, guidelines
• "How we do X here" or past decisions
• Patterns or templates for common tasks
• Reference images, mockups, or design files

neotex search "<query>" --limit 5
neotex search "type:guideline status:active path:backend <query>" --mode hybrid
neotex search "<query>" --source asset --mode lexical
neotex search "<query>" --exact
neotex get <id> --search-id <search_id>   # fetch if score > 0.7
neotex asset get <asset_id> --search-id <search_id>

• Use --mode lexical for exact terms, filenames, or code identifiers
• Use --exact to disable query expansion
• Pass --search-id to help the system learn which results were selected

Precise Content Retrieval (VFS)

For large documents or when you need specific sections:

# Open with line range (like head/tail)
neotex context open <id> --lines 0:100 --max-chars 4000

# Open specific chunk from search result
neotex context open <id> --chunk <chunk_id>

# List items matching filters (like ls)
neotex context list --path /docs --type guideline --source knowledge

• Search results include chunk_id for precise retrieval
• Use --max-chars to limit response size (default 4000)
• Prefer chunk retrieval over full document when search provides chunk_id

When to Store Knowledge

After completing significant work, evaluate:

• Non-obvious solution others would benefit from?
• Decision with tradeoffs worth documenting?
• Reusable pattern or template?

If yes, ask user before storing:

"This involved [description]. Save to neotex as [type]: [title]?"

# Single item
echo '{"type":"learning","title":"...","body_md":"# Title\n\n## Context\n..."}' | neotex add

# Batch from JSON array
echo '[{"type":"guideline","title":"A","body_md":"..."},{"type":"learning","title":"B","body_md":"..."}]' | neotex add --batch

# Streaming batch from JSONL (one JSON per line, memory-efficient)
cat items.jsonl | neotex add --batch --format jsonl --stream

JSONL format (one JSON object per line):

{"type":"guideline","title":"Item 1","body_md":"..."}
{"type":"learning","title":"Item 2","body_md":"..."}

Use --format jsonl --stream for large imports to process items one at a time.

When to Store Assets

IMPORTANT: When users upload reference files, proactively offer to save them to neotex.

Save assets when user provides:

• Reference images (mockups, screenshots, diagrams)
• Design files (logos, icons, UI specs)
• Documentation PDFs
• Configuration files for reference
• Any file they want the team/AI to access later

Prompt user:

"You uploaded [filename]. Save to neotex for future reference? I can add keywords and description for searchability."

# Upload from file path
neotex asset add <filepath> --description "..." --keywords "ui,mockup,login"

# Upload from base64 (useful for API-received content)
neotex asset add --base64 "<base64string>" --filename "image.png" --description "..."

# Upload from stdin (raw binary)
cat image.png | neotex asset add --stdin --filename "image.png" --keywords "..."

# Upload from stdin with base64 encoding
echo "<base64>" | neotex asset add --stdin --encoding base64 --filename "doc.pdf"

# Retrieve an asset
neotex asset get <asset_id> -o <output_path>

Flags for non-file uploads:

• --base64 - Direct base64-encoded content
• --stdin - Read from stdin
• --encoding - Stdin encoding: raw (default) or base64
• --filename - Required with --base64 or --stdin
• --mime-type - Optional, auto-detected from filename

Asset Best Practices

1. Always ask before saving - User may not want file persisted
2. Add descriptive keywords - Makes assets searchable (e.g., "login, mockup, mobile, v2")
3. Include context in description - Why this file matters, what it shows
4. Link to knowledge when relevant - Associate asset with related documentation
5. Retrieve before recreating - Search for existing assets before generating new ones

Knowledge Types

| Type | Use For | |------|---------| | guideline | Rules to follow | | learning | Insights from experience | | decision | Architectural choices | | template | Reusable structures | | checklist | Verification steps | | snippet | Reusable code |

Common Mistakes

• Fetching everything upfront: Search on-demand, not at start
• Storing trivial changes: Only lasting organizational value
• Duplicating: Search before creating
• Storing secrets: Never include credentials or sensitive files
• Ignoring uploaded files: Always offer to save reference materials
• Missing keywords: Assets without keywords are hard to find later