Complete CLI & MCP Reference
Getting Started
gnosys init
Initialize a new .gnosys store in the current directory
gnosys init [options]
Options:
-d, --directory <dir> Target directory (default: cwd)
gnosys config
View and manage LLM provider configuration
gnosys config [command]
Commands:
show Show current LLM configuration
set <key> <value> [extra...] Set a config value
init Generate default gnosys.json
Keys: provider, model, ollama-url, groq-model,
openai-model, lmstudio-url, task <task> <provider> <model>
gnosys stores
Show all active stores, their layers, paths, and permissions
gnosys stores
gnosys doctor
Check system health: stores, LLM connectivity, embeddings
gnosys doctor
gnosys serve
Start the MCP server (stdio mode)
gnosys serve [options]
Options:
--with-maintenance Run maintenance every 6 hours in background
gnosys dashboard
Show system dashboard: memory count, health, graph stats, LLM status
gnosys dashboard [options]
Options:
--json Output as JSON instead of pretty table
Writing Memories
gnosys add
Add a new memory (uses LLM to structure raw input)
gnosys add [options] <input>
Options:
-a, --author <author> Author (human|ai|human+ai) (default: "human")
--authority <authority> Authority (declared|observed|imported|inferred) (default: "declared")
-s, --store <store> Target store (project|personal|global)
gnosys add-structured
Add a memory with structured input (no LLM needed)
gnosys add-structured [options]
Options:
--title <title> Memory title
--category <category> Category directory name
--content <content> Memory content as markdown
--tags <json> Tags as JSON object (default: "{}")
--relevance <keywords> Keyword cloud for discovery (default: "")
-a, --author <author> Author (default: "human")
--authority <authority> Authority level (default: "declared")
--confidence <n> Confidence 0-1 (default: "0.8")
-s, --store <store> Target store
gnosys commit-context
Pre-compaction sweep: extract atomic memories from a context string, check novelty, commit novel ones
gnosys commit-context [options] <context>
Options:
--dry-run Show what would be committed without writing
-s, --store <store> Target store (project|personal|global)
gnosys bootstrap
Batch-import existing documents into the memory store
gnosys bootstrap [options] <sourceDir>
Options:
-p, --pattern <patterns...> File patterns to match (default: **/*.md)
--skip-existing Skip files whose titles already exist
-c, --category <category> Default category (default: "imported")
-a, --author <author> Default author (default: "human")
--authority <authority> Default authority (default: "imported")
--confidence <n> Default confidence 0-1 (default: "0.7")
--preserve-frontmatter Preserve existing YAML frontmatter if present
--dry-run Show what would be imported without writing
-s, --store <store> Target store (project|personal|global)
gnosys import
Bulk import structured data (CSV, JSON, JSONL) into Gnosys memories
gnosys import [options] <fileOrUrl>
Options:
--format <format> Data format: csv, json, jsonl
--mapping <json> Field mapping as JSON
--mode <mode> Processing mode: llm or structured (default: "structured")
--limit <n> Max records to import
--offset <n> Skip first N records
--skip-existing Skip records whose titles already exist
--batch-commit Single git commit for all imports (default: true)
--no-batch-commit Commit each record individually
--concurrency <n> Parallel LLM calls (default: 5)
--dry-run Preview without writing
--store <store> Target store (default: "project")
Reading & Search
gnosys read
Read a specific memory. Supports layer prefix (e.g., project:decisions/auth.md)
gnosys read <memoryPath>
gnosys discover
Discover relevant memories by keyword. Searches relevance clouds, titles, and tags — returns metadata only, no content.
gnosys discover [options] <query>
Options:
-n, --limit <number> Max results (default: "20")
gnosys search
Search memories by keyword across all stores
gnosys search [options] <query>
Options:
-n, --limit <number> Max results (default: "20")
gnosys hybrid-search
Search using hybrid keyword + semantic fusion (RRF)
gnosys hybrid-search [options] <query>
Options:
-l, --limit <n> Max results (default: "15")
-m, --mode <mode> Search mode: keyword | semantic | hybrid (default: "hybrid")
gnosys semantic-search
Search using semantic similarity only (requires embeddings)
gnosys semantic-search [options] <query>
Options:
-l, --limit <n> Max results (default: "15")
gnosys ask
Ask a natural-language question and get a synthesized answer with citations
gnosys ask [options] <question>
Options:
-l, --limit <n> Max memories to retrieve (default: "15")
-m, --mode <mode> Search mode: keyword | semantic | hybrid (default: "hybrid")
--no-stream Disable streaming output
Organization
gnosys list
List all memories across all stores
gnosys list [options]
Options:
-c, --category <category> Filter by category
-t, --tag <tag> Filter by tag
-s, --store <store> Filter by store layer
gnosys lens
Filtered view of memories. Combine criteria to focus on what matters.
gnosys lens [options]
Options:
-c, --category <category> Filter by category
-t, --tag <tags...> Filter by tag(s)
--match <mode> Tag match mode: any or all (default: "any")
--status <statuses...> Filter by status (active, archived, superseded)
--author <authors...> Filter by author (human, ai, human+ai)
--authority <authorities...> Filter by authority (declared, observed, imported, inferred)
--min-confidence <n> Minimum confidence (0-1)
--max-confidence <n> Maximum confidence (0-1)
--created-after <date> Created after ISO date
--created-before <date> Created before ISO date
--modified-after <date> Modified after ISO date
--modified-before <date> Modified before ISO date
--or Combine filters with OR instead of AND
gnosys tags
List all tags in the registry
gnosys tags
gnosys tags-add
Add a new tag to the registry
gnosys tags-add [options]
Options:
--category <category> Tag category (domain, type, concern, status_tag)
--tag <tag> The new tag to add
gnosys links
Show wikilinks for a memory — both outgoing [[links]] and backlinks from other memories
gnosys links <memoryPath>
gnosys graph
Show the full cross-reference graph across all memories
gnosys graph
History & Maintenance
gnosys update
Update an existing memory's frontmatter and/or content
gnosys update [options] <memoryPath>
Options:
--title <title> New title
--status <status> New status (active|archived|superseded)
--confidence <n> New confidence (0-1)
--relevance <keywords> Updated relevance keyword cloud
--supersedes <id> ID of memory this supersedes
--superseded-by <id> ID of memory that supersedes this one
--content <content> New markdown content (replaces body)
gnosys reinforce
Signal whether a memory was useful, not relevant, or outdated
gnosys reinforce [options] <memoryId>
Options:
--signal <signal> Reinforcement signal (useful|not_relevant|outdated)
--context <context> Why this signal was given
gnosys stale
Find memories not modified within a given number of days
gnosys stale [options]
Options:
-d, --days <number> Days threshold (default: "90")
-n, --limit <number> Max results (default: "20")
gnosys history
Show version history for a memory (git-backed)
gnosys history [options] <memoryPath>
Options:
-n, --limit <number> Max entries (default: "20")
--diff <hash> Show diff from this commit to current
gnosys rollback
Rollback a memory to its state at a specific commit
gnosys rollback <memoryPath> <commitHash>
gnosys timeline
Show when memories were created and modified over time
gnosys timeline [options]
Options:
-p, --period <period> Group by: day, week, month, year (default: "month")
gnosys stats
Show summary statistics for the memory store
gnosys stats
gnosys maintain
Run vault maintenance: detect duplicates, apply confidence decay, consolidate similar memories
gnosys maintain [options]
Options:
--dry-run Show what would change without modifying
--auto-apply Automatically apply all changes (no prompts)
gnosys reindex
Rebuild all semantic embeddings from every memory file. Downloads the model (~80 MB) on first run.
gnosys reindex
gnosys reindex-graph
Build or rebuild the wikilink graph (.gnosys/graph.json)
gnosys reindex-graph
Agent Rules
Agent rules allow you to configure custom behavior and preferences for your AI agent. Rules are context directives that shape how the agent operates within your IDE or application. They're particularly useful for enforcing coding standards, specifying project conventions, and providing the agent with important context about your workflow.
Rules are stored as markdown files in your IDE configuration and are automatically included in the agent's context. Here's how to set them up for your preferred IDE:
Save to .cursor/rules/gnosys.mdc — Uses Cursor's .mdc format with YAML frontmatter for alwaysApply: true.
Save to CLAUDE.md at your project root — Concise imperative format with grouped tool table.