neotex

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.

At conversation start, check if neotex is initialized:

```bash

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

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

```bash

neotex search "" --limit 5

neotex search "type:guideline status:active path:backend " --mode hybrid

neotex search "" --source asset --mode lexical

neotex search "" --exact

neotex get --search-id # fetch if score > 0.7

neotex asset get --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

For large documents or when you need specific sections:

```bash

# Open with line range (like head/tail)

neotex context open --lines 0:100 --max-chars 4000

# Open specific chunk from search result

neotex context open --chunk

# 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

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

```bash

# 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.

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."

```bash

# Upload from file path

neotex asset add --description "..." --keywords "ui,mockup,login"

# Upload from base64 (useful for API-received content)

neotex asset add --base64 "" --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 "" | neotex asset add --stdin --encoding base64 --filename "doc.pdf"

# Retrieve an asset

neotex asset get -o

```

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

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

| Type | Use For |

|------|---------|

| guideline | Rules to follow |

| learning | Insights from experience |

| decision | Architectural choices |

| template | Reusable structures |

| checklist | Verification steps |

| snippet | Reusable code |

• 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