Use Gnosys with the behavior the code actually ships.

Install and start

Gnosys supports macOS, Linux, and Windows and requires Node.js 20.12 or newer. The normal local setup keeps the database and MCP server on your machine.

npm install -g gnosys
gnosys setup

cd /path/to/your/project
gnosys init

gnosys setup configures providers, keys, task routing, and supported IDE integrations. gnosys init registers one project and generates current agent rules/hooks for detected clients. After an upgrade or preference change, refresh generated rules with:

gnosys sync --target all

First deterministic memory

gnosys add-structured \
  --title "Use SQLite as source of truth" \
  --category decisions \
  --content "All memory writes go to the central SQLite database."

Connect an MCP client

The recommended route is gnosys setup ides. It writes client-specific configuration that invokes the installed gnosys-mcp wrapper. Claude Desktop and Claude Code are separate integrations, although setup can configure both in one run.

gnosys setup ides --all

Supported setup targets include Claude Desktop, Claude Code, Cursor, Codex, Gemini CLI, Antigravity, and Grok Build. OpenCode can be configured manually as a local MCP command.

Storage model

For ordinary local use, ~/.gnosys/gnosys.db is the sole source of truth. Project directories contain identity and integration files such as .gnosys/gnosys.json, but Gnosys does not write canonical memory Markdown into the repository. Markdown is produced only when you export it.

Everyday workflows

Audit and history views describe recorded operations and supersession metadata. They are not full content snapshots and there is no memory-level rollback command. Use database backups for restore points.

Search modes

Federated ranking

Federated search can rank across scopes with these current multipliers: current project 1.8×, other project context 1.5×, user 1.0×, and global 0.7×. Recency and reinforcement can further affect ranking, and ambiguity detection warns when a query matches multiple projects.

Performance depends on database size, machine, query, and whether embeddings or remote transport are involved. Gnosys does not promise a universal sub-10ms service-level target.

MCP tools: 19 by default, 56 available

Every server registers all 56 OSS tools, but v6.2 starts each session on a smaller 19-tool core tier to reduce schema tokens. The always-available gnosys_toolset tool shows what higher tiers add and can switch the current session to standard, full, or back to core.

Core tools

gnosys_init gnosys_add_structured gnosys_add gnosys_read gnosys_update gnosys_discover gnosys_recall gnosys_search gnosys_hybrid_search gnosys_federated_search gnosys_reinforce gnosys_preference_set gnosys_preference_get gnosys_briefing gnosys_dashboard gnosys_trace gnosys_reflect gnosys_traverse gnosys_toolset

Standard additions

gnosys_list gnosys_stats gnosys_tags gnosys_timeline gnosys_working_set gnosys_semantic_search gnosys_ask gnosys_lens gnosys_links gnosys_graph gnosys_attach gnosys_get_attachment gnosys_ingest_file gnosys_update_status gnosys_preference_delete

Full-tier additions

gnosys_tags_add gnosys_migrate gnosys_stale gnosys_commit_context gnosys_history gnosys_bootstrap gnosys_import gnosys_reindex gnosys_maintain gnosys_dearchive gnosys_reindex_graph gnosys_dream gnosys_export gnosys_stores gnosys_audit gnosys_sync gnosys_detect_ambiguity gnosys_portfolio gnosys_remote_status gnosys_remote_push gnosys_remote_pull gnosys_remote_resolve

Set GNOSYS_MCP_TOOLSET=core|standard|full to choose a starting tier. Agents can still change it within their own session.

Current CLI inventory

The package exposes the following command paths. Use gnosys <command> --help for exact options; the generated reference is linked below. Removed commands such as rollback, prune, and the old top-level dashboard are not part of the current CLI.

LLM providers and routing

The OSS package supports nine provider types: Anthropic, Ollama, Groq, OpenAI, LM Studio, xAI, Mistral, OpenRouter, and custom OpenAI-compatible endpoints. There is no universal default provider for LLM-backed work; run setup and verify each task you plan to use.

gnosys setup providers
gnosys setup models
gnosys setup routing
gnosys check --task structuring

Task routing uses taskModels.structuring, synthesis, vision, transcription, and dream. Legacy multimodal routing fields remain supported. API keys can come from config, scoped environment names, OS key storage, legacy provider variables, or ~/.config/gnosys/.env; see the configuration reference for precedence.

Files, media, and attachments

gnosys ingest and gnosys_ingest_file support local text and media pipelines. The default maximum input size is 100 MB and can be changed in multimodal configuration.

ingest versus attach

• ingest processes a filesystem file into one or more memories. Large/source attachments remain local filesystem artifacts and are not a portable binary-sync guarantee.
• attach stores one small binary inline on a memory, up to roughly 10 MiB. Inline attachments travel with supported database synchronization and remote-server flows.

Safe multi-machine use

Choose one of two supported topologies. Neither topology mounts one live SQLite database concurrently on multiple machines.

Option A: v13 snapshot and staged-write sync

1. The master keeps its writable gnosys.db on the master machine's local disk.
2. The master publishes a checksummed snapshot to a path clients can reach through a shared folder or VPN-mounted path.
3. Clients read their last accepted snapshot. If the master path is temporarily unreachable, that snapshot remains readable but may be stale.
4. Clients stage new add-only writes for later master ingestion. Client update, reinforce, and delete operations are deferred.

gnosys setup remote
gnosys setup remote status
gnosys setup remote doctor

gnosys setup remote timer installs background ingest scheduling on macOS or Linux. Offline staging is local-only unless you back it up separately.

Option B: one network-hosted MCP server

Run one Gnosys server beside a host-local database, then point clients to its MCP URL. Clients have one live brain but no memory access while that server is unreachable.

# trusted host; loopback is the default
gnosys serve --transport http --host 127.0.0.1 --port 7777

# configure a client
gnosys connect --url http://host:7777/mcp --token YOUR_TOKEN

Grok Bot integration for multi-agent teams

This pattern gives multi-agent Grok Bot teams persistent shared memory through one dedicated seat that owns the local gnosys installation. Sibling Grok Bots message that seat via SendToAgent; they never run the CLI directly or attach gnosys-mcp.

Architecture

• A dedicated Grok Bot seat named "Gnosys" runs gnosys via machine Shell, cwd-scoped into registered projects
• Sibling Grok Bots do NOT run the CLI; they message the Gnosys seat (SendToAgent) for RECALL / QUERY / SAVE / REINFORCE
• Do NOT attach gnosys-mcp on the Grok Bot computer for this pattern
• Do NOT put the live DB on iCloud / Dropbox / SMB
• Bare install: packaged Gnosys bot ships with skill gnosys-bot-operating-system only (no prior memories/projects)

Install (once per machine)

npm install -g gnosys
gnosys setup
which gnosys && gnosys --version

Node 20.12+ required. gnosys setup configures optional LLM features; basic memory works without a provider.

Init (once per project)

cd "/absolute/path/to/project"
gnosys init

Or specify explicitly:

gnosys init -d "/abs/path" -n "Project Name"

Recommended first project: ops / Grok Bot working folder named "Grok Bot".

Bootstrap the Gnosys Grok Bot seat

1. Install/share the Gnosys bot; note its current agent id (never a stale template id)
2. Confirm CLI + brain; init ops project
3. Patch sibling bots: recall sends to Gnosys seat via SendToAgent; durable decisions SendToAgent SAVE to the Gnosys seat (only that seat runs gnosys add-structured)
4. Optional: migrate that install's own agent memories only; never another operator's data; skip secrets
5. Local-exec / Shell must be allowed for the Gnosys seat on the machine holding gnosys

Message protocol (for sibling agents)

Sibling Grok Bots SendToAgent these messages to the Gnosys seat. Only the Gnosys seat runs gnosys CLI commands.

• RECALL/QUERY: project (absolute cwd or federated) + query + author
• SAVE: project, title, category, content, relevance, author, tags {"agent":"SeatName"}
• REINFORCE: id + useful | not_relevant | outdated
• The Gnosys seat translates SAVE to gnosys add-structured (no freeform gnosys add). add-structured has no -d flag; the seat must cd to the project directory first.

Sample messages

RECALL example:

SendToAgent "Gnosys":
RECALL project="/Users/operator/projects/api-service" query="authentication middleware design decisions" author="CodeBot"

SAVE example:

SendToAgent "Gnosys":
SAVE project="/Users/operator/projects/api-service" title="Use JWT for API auth" category="decisions" content="Selected JWT tokens over session cookies for stateless API authentication. Tokens expire after 15 minutes with refresh token rotation." relevance="high" author="CodeBot" tags={"agent":"CodeBot","auth":"jwt"}

Backup, restore, and export

Local backups are explicit, not automatic. Run them before risky maintenance or migration work and copy the resulting file to storage with an appropriate retention policy.

gnosys backup --to ./backups
gnosys restore ./backups/gnosys-backup-TIMESTAMP.db
gnosys export vault --to ./obsidian-vault

• backup uses SQLite's backup API and creates a timestamped DB file in the chosen directory. If a sandbox log exists, it is copied too.
• restore replaces the active central DB. Close Gnosys processes first and verify the exact backup file.
• export vault is a one-way human-readable Markdown export. It does not replace a database backup.
• Configured v13 masters can create their own scheduled snapshot retention, but that does not make every local installation automatically backed up.

Sandbox, helper, tracing, and status

Sandbox and generated helper

The optional background sandbox listens on a local Unix socket or Windows named pipe. gnosys helper generate creates a small TypeScript helper with seven common operations: add, recall, reinforce, list, stats, reflect, and traverse.

gnosys sandbox start
gnosys helper generate --directory ./agent
gnosys sandbox status

The helper reduces MCP schema overhead for scripts, but it does not provide the entire CLI or MCP surface.

Process tracing

trace, reflect, and traverse are available through CLI and MCP. Current code tracing is a best-effort static regex analysis for JavaScript, TypeScript, JSX, and TSX; it is not a language-server call graph or runtime profiler.

Portfolio and status

gnosys status reports one project, --projects reports the portfolio, --system reports system health, and --web generates an HTML dashboard. Automatic opening is currently macOS-specific; on other platforms open the generated file yourself.

Web Knowledge Base

The gnosys/web subpath and gnosys web commands build a website-oriented knowledge directory and precomputed JSON search index. The runtime search module avoids native dependencies, so it can be used in serverless Node applications.

gnosys web init
gnosys web ingest
gnosys web build-index
gnosys web status

• Keyword search uses the precomputed index with no database at runtime.
• Optional build-time vectors enable hybrid search, but the application must embed queries with a compatible model.
• Your site's llms.txt can reference the generated knowledge content; Gnosys does not currently generate a complete llms.txt policy file for you.

Agent discovery and project metadata API

gnosys.ai publishes a small public metadata API so software agents can identify the package, find its canonical documentation, and verify that the metadata service is available. It also operates a deliberately limited OAuth-protected Agent Profile API for standards-based registration and discovery testing. Neither API exposes a hosted Gnosys memory database or hosted MCP endpoint.

GET https://gnosys.ai/api/v1/project.json
GET https://gnosys.ai/api/v1/status.json
GET https://gnosys.ai/api/v1/agent/status   # public D1/crypto readiness
GET https://gnosys.ai/api/v1/agent/profile  # OAuth bearer token required

The project and readiness endpoints require no authentication. The dynamic Agent Profile readiness check validates its D1 schema and signing configuration without returning registration data. The agent profile endpoint accepts only the agent.profile:read scope and returns registration metadata, including explicit hosted_memory_api: false and hosted_mcp_server: false fields.

Machine-readable discovery is published at:

• /.well-known/openapi.json — OpenAPI 3.1 service description.
• /.well-known/api-catalog — API catalog in Linkset JSON.
• /.well-known/oauth-protected-resource — RFC 9728 protected-resource metadata.
• /.well-known/oauth-authorization-server — RFC 8414 authorization-server metadata.
• /.well-known/jwks.json — public ES256 verification keys.
• /.well-known/agent-skills/index.json — Gnosys memory skill discovery index.
• /server.json — MCP Registry-style npm and local stdio installation metadata.
• /.well-known/mcp/server-card.json — compatibility metadata for the user-operated local MCP server; it explicitly does not advertise a hosted endpoint.
• /auth.md — complete agent registration, token, claim, protected-resource, and revocation instructions.

The OAuth server supports authorization code with mandatory PKCE S256 and a one-time JWT bearer assertion returned by anonymous agent registration. Access tokens expire after ten minutes and can be revoked. See /auth.md for the exact flow and retention limits.

Agents can request canonical HTML pages with Accept: text/markdown to receive a Markdown representation. The homepage also advertises the catalog, OpenAPI document, guide, agent skill index, and local MCP package descriptor through RFC 8288 Link response headers.

Security, privacy, and cost

Imported documents and retrieved web content can contain prompt-injection text. Gnosys applies controls, but no retrieval system can eliminate that risk. Treat untrusted content as data, keep tool permissions narrow, and review sensitive actions.

Important limits and non-features

• There is no memory-level rollback feature. Audit/history metadata is not a full content version store.
• Bulk import supports CSV, JSON, JSONL, field mapping, dry-run, offset/limit, and skip-existing. It does not have durable checkpoint/resume or transactional batch commits.
• Dream Mode is opt-in and never deletes memories, but its critique, summary, and relationship phases can require a configured LLM.
• The Web Knowledge Base is serverless-Node friendly; that does not imply every edge runtime can execute every build or embedding path.
• Windows paths and named pipes are implemented, but some convenience automation is platform-specific: remote timers are macOS/Linux and dashboard auto-open is currently macOS.
• Gnosys is a local-first, single-user/small-trusted-group memory system. Multi-tenant authentication, authorization, quotas, TLS, and hosted operations are outside the OSS server's scope.