Neotex Knowledge Integration

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]?"

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

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 an asset
neotex asset add <filepath> --description "..." --keywords "ui,mockup,login"

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

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

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