# Gnosys full documentation Published npm version: 7.0.0 # Gnosys User Guide — OSS v7 Source: https://gnosys.ai/docs ## Install and start Gnosys supports macOS, Linux, and Windows and requires Node.js **^22.16.0 || >=24.0.0**. The normal local setup keeps the database and MCP server on your machine. ```text 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: ```text gnosys sync --target all ``` **No LLM is required for core memory.** Reads, FTS5 keyword search, and `gnosys add-structured` work without a provider. Configure an LLM only for features that synthesize or structure content. ### First deterministic memory ```text 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 After `npm install -g gnosys`, the recommended route is `gnosys setup ides`. It writes client-specific configuration that invokes `gnosys-mcp` with no args, equivalent to `gnosys serve`. Without a global install, use `npx -y gnosys serve`. Both launch the MCP stdio server. The wrapper comes from the installed `gnosys` package; the standalone `gnosys-mcp` npm package is unpublished. Claude Desktop and Claude Code are separate integrations, although setup can configure both in one run. ```text 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. [npm package](https://www.npmjs.com/package/gnosys) [Setup walkthrough](https://github.com/proticom/gnosys/blob/v7.0.0/docs/setup-walkthrough.md) [Configuration reference](https://github.com/proticom/gnosys/blob/v7.0.0/docs/configuration.md) ## 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. ### Project scope Memories are associated with one registered project in the central DB. They are scoped to the codebase; they do not physically live beside the code. ### User scope Personal preferences and conventions can apply across registered projects on the same brain. ### Global scope Knowledge can be visible across projects in this Gnosys installation. It is not an organization-wide service unless you deliberately host or synchronize it. ### SQLite features FTS5 keyword search, optional embeddings, audit metadata, relationships, attachments, project identity, and sync metadata live in the database. **Never put the live database on iCloud, Dropbox, OneDrive, SMB, NFS, or another shared filesystem.** Concurrent network/cloud access to live SQLite pages can corrupt the database. Keep every live writer's DB on local disk and use one of the supported multi-machine topologies below. ## Everyday workflows | Goal | CLI | MCP guidance | Find likely context quickly | `gnosys discover "query"` | Call `gnosys_discover`, then `gnosys_read` for selected results. | Write a known structure | `gnosys add-structured` | Agents should use `gnosys_add_structured`. It makes no server-side LLM call. | Structure raw text | `gnosys add "raw text"` | `gnosys_add` is rejected over MCP by default; it is intended for opted-in non-agent callers. | Mark usefulness | `gnosys reinforce ` | `gnosys_reinforce` accepts useful, not-relevant, or outdated signals. | Review current health | `gnosys status --system` | `gnosys_dashboard` returns structured system data. | Update project status | `gnosys update-status` | `gnosys_update_status` returns the eight-section status-writing instructions. | Export for humans | `gnosys export vault --to ./vault` | `gnosys_export` creates an Obsidian-compatible one-way export. 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 ### Keyword FTS5 matching works locally without an LLM or embedding model. Use `search` or lightweight `discover`. ### Semantic Embedding similarity finds conceptual matches. Run `gnosys reindex` first; the optional local transformer package may download a model on first use. ### Hybrid Combines keyword and semantic ranks with reciprocal-rank fusion. It needs the semantic index. ### Ask Runs hybrid retrieval, then sends selected context to a configured LLM to synthesize a cited answer. ### 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 Gnosys 7.0.0 starts each session on the 19-tool core tier to reduce schema tokens and can expand to all 56 tools on demand. The always-available `gnosys_toolset` tool shows what higher tiers add and can switch the current session to `standard`, `full`, or back to `core`. | Tier | Count | What it covers | Core (default) | 19 | Initialize, deterministic writes, read/update, core search, reinforcement, preferences, briefing/dashboard, process tracing, and tier switching. | Standard | 34 | Core plus browsing, semantic/ask/lens/graph, attachments, file ingestion, status, and preference deletion. | Full | 56 | All import/export, maintenance, remote sync, archive, debug, and portfolio tools. ### 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` **Agent write safety.** `gnosys_add` is rejected over MCP unless the operator sets `GNOSYS_ALLOW_FREEFORM_ADD=1`. AI agents should provide explicit fields to `gnosys_add_structured`. Set `GNOSYS_MCP_TOOLSET=core|standard|full` to choose a starting tier. Agents can still change it within their own session. [Generated MCP reference](https://github.com/proticom/gnosys/blob/v7.0.0/docs/mcp-tools.md) [Toolset tiers](https://github.com/proticom/gnosys/blob/v7.0.0/docs/mcp-toolsets.md) ## Current CLI inventory The package exposes the following command paths. Use `gnosys --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. Setup, configuration, and diagnostics - `gnosys setup` - `gnosys setup providers` - `gnosys setup keys` - `gnosys setup models` - `gnosys setup dream` - `gnosys setup ides` - `gnosys setup routing` - `gnosys setup preferences` - `gnosys setup sync-projects` - `gnosys config` - `gnosys config show` - `gnosys config set` - `gnosys config init` - `gnosys check` - `gnosys doctor` - `gnosys upgrade` Memory, discovery, and relationships - `gnosys init` - `gnosys read` - `gnosys discover` - `gnosys search` - `gnosys list` - `gnosys add` - `gnosys add-structured` - `gnosys update` - `gnosys reinforce` - `gnosys stale` - `gnosys tags` - `gnosys tags-add` - `gnosys lens` - `gnosys history` - `gnosys timeline` - `gnosys stats` - `gnosys links` - `gnosys graph` - `gnosys commit-context` - `gnosys recall` - `gnosys recall-hook` - `gnosys working-set` Search, embeddings, and synthesis - `gnosys reindex` - `gnosys hybrid-search` - `gnosys semantic-search` - `gnosys ask` - `gnosys fsearch` - `gnosys ambiguity` - `gnosys reindex-graph` - `gnosys briefing` Files, import, maintenance, and portability - `gnosys ingest` - `gnosys attach` - `gnosys get-attachment` - `gnosys bootstrap` - `gnosys import` - `gnosys import project` - `gnosys export` - `gnosys export vault` - `gnosys export project` - `gnosys audit` - `gnosys backup` - `gnosys restore` - `gnosys migrate` - `gnosys migrate-db` - `gnosys maintain` - `gnosys dearchive` - `gnosys cleanup` Projects, preferences, machines, and status - `gnosys stores` - `gnosys centralize` - `gnosys connect` - `gnosys machine` - `gnosys machine show` - `gnosys machine migrate` - `gnosys machine list` - `gnosys machine forget` - `gnosys scan` - `gnosys projects` - `gnosys pref` - `gnosys pref set` - `gnosys pref get` - `gnosys pref delete` - `gnosys sync` - `gnosys status` - `gnosys update-status` Multi-machine synchronization - `gnosys setup remote` - `gnosys setup remote status` - `gnosys setup remote push` - `gnosys setup remote pull` - `gnosys setup remote sync` - `gnosys setup remote resolve` - `gnosys setup remote doctor` - `gnosys setup remote timer` Dream Mode, sandbox, helpers, and tracing - `gnosys dream` - `gnosys dream run` - `gnosys dream log` - `gnosys dream report` - `gnosys sandbox` - `gnosys sandbox start` - `gnosys sandbox stop` - `gnosys sandbox status` - `gnosys helper` - `gnosys helper generate` - `gnosys trace` - `gnosys reflect` - `gnosys traverse` MCP server and Web Knowledge Base - `gnosys serve` - `gnosys web` - `gnosys web init` - `gnosys web ingest` - `gnosys web build-index` - `gnosys web build` - `gnosys web add` - `gnosys web remove` - `gnosys web update` - `gnosys web status` [Generated CLI reference](https://github.com/proticom/gnosys/blob/v7.0.0/docs/cli.md) [Per-command guides](https://github.com/proticom/gnosys/tree/v7.0.0/docs/commands) ## 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. ```text gnosys setup providers gnosys setup models gnosys setup routing gnosys check --task structuring ``` | Task | Needs a provider? | Notes | Structured memory write | No | `add-structured` and `gnosys_add_structured` are deterministic. | Raw-text structuring | Yes | Used by `gnosys add` and LLM-mode imports. | Ask / synthesis | Yes | Retrieved memory context is sent to the configured synthesis provider. | Dream LLM phases | Yes | Dream Mode is opt-in; local Ollama can avoid cloud billing. | Vision | Yes | The chosen provider/model must support image input. | Transcription | Yes or local | Groq/OpenAI APIs, or local Whisper through the optional transformers package. 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. | Input | Processing | Extra requirement | TXT, Markdown | Local text read, chunking, then structured or LLM mode | LLM only for LLM mode | PDF, DOCX | Local parser extracts text, then chunking | LLM only for LLM mode | PNG, JPEG, GIF, WebP, SVG | Vision model creates a description | Vision-capable provider/model | MP3, WAV, M4A, OGG, FLAC, WebM audio | Transcription, then chunking | Groq/OpenAI key or local Whisper | MP4, MKV, MOV, AVI, WebM video | Extract audio, transcribe, then chunk | `ffmpeg` plus transcription route ### `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. **Cloud disclosure.** If you select a cloud provider, applicable extracted text, prompts, images, or audio are sent to that provider. Use Ollama, LM Studio, or local Whisper when content must remain on the machine, and verify the selected model actually supports the task. ## 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 - The master keeps its writable `gnosys.db` on the master machine's local disk. - The master publishes a checksummed snapshot to a path clients can reach through a shared folder or VPN-mounted path. - Clients read their last accepted snapshot. If the master path is temporarily unreachable, that snapshot remains readable but may be stale. - Clients stage new add-only writes for later master ingestion. Client update, reinforce, and delete operations are deferred. ```text 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. ```text # 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 ``` **Network exposure is an operator responsibility.** Non-loopback binds require a bearer token. Gnosys does not provide built-in TLS or rate limiting; use a trusted tailnet or a reverse proxy, and do not expose the server directly to the public internet. [v13 sync details](https://github.com/proticom/gnosys/blob/v7.0.0/docs/multi-machine-sync-v13.md) [Network MCP guide](https://github.com/proticom/gnosys/blob/v7.0.0/docs/network-mcp.md) ## 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) ```text npm install -g gnosys gnosys setup which gnosys && gnosys --version ``` Node.js ^22.16.0 or >=24.0.0 required. `gnosys setup` configures optional LLM features; basic memory works without a provider. ### Init (once per project) ```text cd "/absolute/path/to/project" gnosys init ``` Or specify explicitly: ```text 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 - Install/share the Gnosys bot; note its **current** agent id (never a stale template id) - Confirm CLI + brain; init ops project - 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`) - Optional: migrate that install's own agent memories only; never another operator's data; skip secrets - 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:** ```text SendToAgent "Gnosys": RECALL project="/Users/operator/projects/api-service" query="authentication middleware design decisions" author="CodeBot" ``` **SAVE example:** ```text 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"} ``` [Dedicated landing page](/grok-bot) [GitHub](https://github.com/proticom/gnosys) ## 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. ```text 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. ```text 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. ```text 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. [Web KB quick guide](/web-knowledge-base.md) [Semantic Web KB details](https://github.com/proticom/gnosys/blob/v7.0.0/docs/web-semantic-search.md) ## 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. ```text 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. **OAuth is isolated from Gnosys memory.** Anonymous registrations are short-lived, rate-limited, and stored in a dedicated Cloudflare D1 database. Access tokens can read only the caller's registration profile. A self-hosted `gnosys serve --transport http` instance is still operated and secured by its owner; credentials issued by gnosys.ai never authorize it. 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. [API catalog](/.well-known/api-catalog) [OpenAPI](/.well-known/openapi.json) [Agent skills](/.well-known/agent-skills/index.json) [MCP installation metadata](/server.json) [Agent authentication guide](/auth.md) ## Security, privacy, and cost ### Local data The SQLite DB and inline blobs are not application-layer encrypted. Use OS permissions, full-disk encryption, and protected backups. ### Provider data Configured cloud providers receive the prompts, retrieved context, or media required for their task. Their retention and billing terms apply. ### Secrets Setup can use macOS Keychain or Linux secret storage when available, otherwise scoped environment variables or the local env file. ### Cost controls Gnosys does not track cumulative tokens, dollars, daily spend, or enforce a budget. Configure hard limits with each provider. 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. [Threat model](https://github.com/proticom/gnosys/blob/v7.0.0/docs/threat-model.md) [Cost and limits](https://github.com/proticom/gnosys/blob/v7.0.0/docs/cost-and-limits.md) [Security policy](https://github.com/proticom/gnosys/blob/v7.0.0/SECURITY.md) ## 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. **Source of truth for details.** The installed command's `--help`, generated CLI/MCP references, and tagged OSS source take precedence if this page ever drifts. Please report a mismatch as a GitHub issue. [Report documentation drift](https://github.com/proticom/gnosys/issues) [Release notes](https://github.com/proticom/gnosys/releases) [Published npm package](https://www.npmjs.com/package/gnosys) --- # Gnosys — Persistent Memory for AI Agents Source: https://gnosys.ai/ Open Source · MIT License # Persistent memory for AI agents Gnosys gives AI agents persistent, portable, shared memory across sessions and projects. It starts with a compact core MCP toolset and expands to the full toolset on demand, with 9 LLM providers, federated search, multimodal ingestion, a serverless Web Knowledge Base, process tracing, and Dream Mode consolidation. macOS · Linux · Windows [View on GitHub](https://github.com/proticom/gnosys) [View on npm](https://www.npmjs.com/package/gnosys) [See how it works](#how-it-works) $ `npm install -g gnosys` copy How it works ## Watch an agent remember An agent saves a decision on Monday. On Thursday a new session finds it, and so does a different agent. Every tool call is a real Gnosys MCP tool with its real arguments. ### 1 Remember a decision **Claude Code** · acme-api Mon 5 Oct · 2:04 pm Monday, 2:04 pm A Claude Code session in the acme-api project. Chat YouRemember: we decided to use Postgres row-level security for tenant isolation, not app-level filters. AgentI'll check Gnosys for an existing memory first. Called `gnosys_discover` Called `gnosys_add_structured` AgentSaved to Gnosys as `deci-01KZ7Q3M8T4VXN2R6HJCW5PB9E` under decisions. Future sessions in this project can recall it. Gnosys MCP tool calls `gnosys_discover`done ```text { "query": "tenant isolation postgres row-level security", "projectRoot": "/Users/sam/code/acme-api" } ``` ```text No memories found for "tenant isolation postgres row-level security". Try different keywords. ``` `gnosys_add_structured`done ```text { "title": "Tenant isolation uses Postgres row-level security", "category": "decisions", "tags": { "domain": ["database", "multi-tenant"], "type": ["decision"] }, "relevance": "tenant isolation postgres rls row-level security multi-tenant app-level filters", "content": "Use Postgres row-level security for tenant isolation. Do not rely on app-level WHERE filters.", "author": "human+ai", "authority": "declared", "projectRoot": "/Users/sam/code/acme-api" } ``` ```text Memory added to [project]: **Tenant isolation uses Postgres row-level security** ID: deci-01KZ7Q3M8T4VXN2R6HJCW5PB9E ``` - A developer states a decision in chat. Nothing is saved yet. - The agent calls gnosys_discover to check for a duplicate. Nothing matches. - gnosys_add_structured saves the decision. The agent writes the title, category, tags and keywords itself. - The memory now lives in ~/.gnosys/gnosys.db, outside the chat, with a stable ID. ### 2 Recall it in a new session **Claude Code** · acme-api · new session Thu 8 Oct · 9:12 am 3 days later Thursday, 9:12 am. A new session with an empty context window. Chat YouWhat did we decide for tenant isolation? Called `gnosys_recall` Called `gnosys_read` AgentYou decided to use Postgres row-level security for tenant isolation, not app-level filters. Source: `deci-01KZ7Q3M8T4VXN2R6HJCW5PB9E`, a declared decision saved Monday 5 October. Gnosys MCP tool calls `gnosys_recall`done ```text { "query": "tenant isolation decision", "projectRoot": "/Users/sam/code/acme-api" } ``` ```text [Memory 1] [[deci-01KZ7Q3M8T4VXN2R6HJCW5PB9E]] (relevance: 1.00) # Tenant isolation uses Postgres row-level security Use Postgres row-level security for tenant isolation. Do not rely on app-level WHERE filters. [Memory 2] [[arch-01KYV2D7RJ0C4XH9N6TQM3B8WS]] (relevance: 0.64) # Tenant ID comes from the session token The API sets app.tenant_id from the signed session token on every request. [Memory 3] [[deci-01KYN8F5ZB3K7PQW2HXD4C6M1R]] (relevance: 0.30) # Primary database is Postgres 17 We run one managed Postgres 17 instance per region. ``` `gnosys_read`done ```text { "path": "deci-01KZ7Q3M8T4VXN2R6HJCW5PB9E", "projectRoot": "/Users/sam/code/acme-api" } ``` ```text [Source: gnosys.db] --- id: deci-01KZ7Q3M8T4VXN2R6HJCW5PB9E title: 'Tenant isolation uses Postgres row-level security' category: decisions tags: {"domain":["database","multi-tenant"],"type":["decision"]} author: human+ai authority: declared confidence: 0.8 status: active created: '2026-10-05' --- # Tenant isolation uses Postgres row-level security Use Postgres row-level security for tenant isolation. Do not rely on app-level WHERE filters. ``` - Three days later, a new session starts with no chat history. - gnosys_recall searches the project's memories by keyword and ranks them. - gnosys_read loads the top hit by ID, with who declared it and when. - The answer cites the memory ID, so you can check where it came from. ### 3 Use it from another agent **Codex** · acme-api Thu 8 Oct · 9:40 am Same morning, another agent Codex in the same project, connected to the same Gnosys database. Chat YouAdd an invoices table for the billing service. Called `gnosys_recall` AgentCreated `migrations/0042_invoices.sql` with row-level security on the new table, per `deci-01KZ7Q3M8T4VXN2R6HJCW5PB9E`. ```text CREATE TABLE invoices ( id uuid PRIMARY KEY, tenant_id uuid NOT NULL, amount_cents bigint NOT NULL ); ALTER TABLE invoices ENABLE ROW LEVEL SECURITY; CREATE POLICY tenant_isolation ON invoices USING (tenant_id = current_setting('app.tenant_id')::uuid); ``` Gnosys MCP tool calls `gnosys_recall`done ```text { "query": "invoices table tenant database", "projectRoot": "/Users/sam/code/acme-api" } ``` ```text [Memory 1] [[deci-01KZ7Q3M8T4VXN2R6HJCW5PB9E]] (relevance: 1.00) # Tenant isolation uses Postgres row-level security Use Postgres row-level security for tenant isolation. Do not rely on app-level WHERE filters. [Memory 2] [[arch-01KYV2D7RJ0C4XH9N6TQM3B8WS]] (relevance: 0.30) # Tenant ID comes from the session token The API sets app.tenant_id from the signed session token on every request. ``` - Same morning, a different agent. Codex reads the same local Gnosys database. - Codex recalls the tenant isolation decision before it writes any code. - The decision shapes new code in another tool. Nobody had to repeat it. Gnosys Gnosys ### Give your agents a memory ```text npm install -g gnosys gnosys setup ``` [Read the docs](/docs) [View on GitHub](https://github.com/proticom/gnosys) - Install Gnosys and run setup to connect it to your agents. 0:00 / 0:54 The project, people, IDs and times are examples. Tool names, arguments and result formats match Gnosys OSS. - ### Save The agent checks for a duplicate with `gnosys_discover`, then writes with `gnosys_add_structured`. It supplies the title, tags and keywords, so storing needs no LLM call. - ### Store The memory lives in `~/.gnosys/gnosys.db`, scoped to the project. Closing the chat does not lose it. - ### Recall `gnosys_recall` ranks matches by keyword with no LLM call. `gnosys_read` loads one by ID. - ### Share Every MCP client on the machine reads the same database. Claude Code, Cursor and Codex see the same memory. Features ## Everything agents need to remember A local-first SQLite brain that starts agents on a compact core MCP toolset and expands to the full toolset on demand. Fast local recall, federated search, multimodal ingestion, process tracing, Dream Mode, and a serverless Web Knowledge Base are included in the OSS package. Verification note, 25 October 2026: these claims were checked against the open-source v7.0.0 codebase. The current npm release is v7.0.0. Feature prerequisites and limitations are documented in the [user guide](/docs). ### Centralized Brain One local `~/.gnosys/gnosys.db` is the source of truth across projects. FTS5, optional embeddings, local recall, manual SQLite backup/restore, and one-command Obsidian export are built in. ### Federated Search Cross-scope search with tier boosting: current project 1.8x, project 1.5x, user 1.0x, global 0.7x. Recency and reinforcement boosting. Ambiguity detection across projects. ### Three-Scope Architecture Project, user, and global scopes share one central DB. Project memories stay scoped to their codebase, user preferences apply across projects, and global knowledge is visible across registered projects on this brain. ### Memory Lensing Filter by category, tags, status, author, confidence, dates. Compound lenses combine criteria with AND/OR logic. ### Audit Log & Export Supported MCP writes and maintenance actions are recorded in the audit log. Inspect history and supersession links, or export an Obsidian-compatible Markdown vault with `gnosys export vault --to`. Restore points come from explicit database backups. ### Obsidian Wikilinks Cross-reference memories with [[wikilinks]]. Build a knowledge graph with backlinks, see connections, find orphaned links. ### LLM Ingestion The CLI can feed raw text to a configured LLM for atomic structuring. Agents can use `gnosys_add_structured` for deterministic writes that need no LLM provider. ### Dream Mode Opt-in consolidation can apply confidence decay and run LLM-backed self-critique, summaries, and relationship discovery. Dream Mode never deletes memories. ### Bulk Import Import CSV, JSON, or JSONL with field mapping, dry runs, offset/limit controls, and skip-existing deduplication. Choose LLM structuring or the faster structured path. ### Multi-Project + Preferences Central project registry, routing through project identity and registered locations, project briefings, user preferences, and generated agent rules for Claude Code, Cursor, Codex, and more. ### Web Knowledge Base Turn a website into a `/knowledge/` directory of searchable Markdown. A pre-computed JSON index supports a dependency-free Node runtime; optional build-time vectors add hybrid semantic search. The generated content can be referenced from [llms.txt](https://llmstxt.org). For AI agents: [llms.txt](/llms.txt), [full docs](/llms-full.txt), [guide](/docs), [MCP metadata](/server.json), [API catalog](/.well-known/api-catalog), and [agent skills](/.well-known/agent-skills/index.json). ### Sandbox Runtime Run a persistent local helper service over a Unix socket or Windows named pipe. A generated TypeScript helper exposes seven common memory operations without loading MCP tool schemas. ### Process Tracing Build call chains with `leads_to`, `follows_from`, and `requires` relationships. Reflect on outcomes to update confidence. Trace, reflect, and traverse are available through both CLI and MCP. ### Portfolio Dashboard Cross-project status dashboard with readiness scores, blocker tracking, and production-readiness assessment. `gnosys status --web` generates interactive HTML and currently auto-opens it on macOS. ### Guided Status Updates `gnosys update-status` walks AI agents through an 8-section checklist to create comprehensive status snapshots covering progress, blockers, risks, and next steps. ### Multimodal Ingestion Ingest PDF, DOCX, text, images, audio, and video through CLI or MCP. Images require a vision-capable model; audio requires Groq, OpenAI, or local Whisper; video also requires `ffmpeg`. ### Multi-Machine Sync Keep the master SQLite DB on the master machine's local disk. Clients read a checksummed published snapshot and stage add-only offline writes through a shared folder or VPN path—never a concurrently mounted live database. [Check token costs and break-even](/token-savings) Grok Bot Integration ## Persistent memory for multi-agent Grok Bot teams One dedicated Grok Bot seat runs local gnosys so your team never blocks on the CLI. Shared SQLite brain, project-scoped memory, and SendToAgent messaging keep every agent in sync. ### Architecture Sibling Grok Bots SendToAgent → Gnosys Gnosys Seat Runs `gnosys` via Shell SQLite Brain Local disk only - Dedicated Gnosys seat named "Gnosys" runs `gnosys` via machine Shell, cwd-scoped into registered projects - Sibling Grok Bots do NOT run the CLI; they SendToAgent messages to the Gnosys seat for RECALL / QUERY / SAVE / REINFORCE - Do NOT attach `gnosys-mcp` on Grok Bot's 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 [Learn More](/grok-bot) [Integration Guide](/docs#grok-bot) Setup ## Add to your editor in 2 minutes Gnosys is an MCP server. Point your AI client at it, and your agent gains persistent memory. **Recommended setup (two commands):** **1. Machine (once):** `npm install -g gnosys` then `gnosys setup` — configures your LLM provider, API keys, and IDE MCP servers. MCP-only shortcut: `gnosys setup ides --all`. **2. Per project (each codebase):** `gnosys init` — registers the project, writes agent rules/hooks for your detected IDE (`.cursor/rules/gnosys.mdc`, `CLAUDE.md`, Codex hooks, etc.), and wires MCP for project-level IDEs. **Optional:** `gnosys sync --target all` refreshes rules with your preferences and project decisions. `gnosys sync --global` updates machine-wide `~/.claude/CLAUDE.md`. *Cowork users:* Cowork has no working directory of its own; once gnosys is registered with Claude Desktop, the agent uses `projectRoot` to scope memory to whichever codebase you're discussing. ### 1. MCP Server Config — manual fallback After `npm install -g gnosys`, `gnosys setup ides` writes the `gnosys-mcp` wrapper with **no args**, equivalent to `gnosys serve`. Setup resolves the absolute path on your machine. Without a global install, use `npx -y gnosys serve`. Both launch the MCP stdio server. claude_desktop_config.json ```text { "mcpServers": { "gnosys": { "command": "gnosys-mcp", "args": [] } } } ``` This config covers Claude Desktop surfaces such as **Chat and Cowork**. Claude Code is a separate integration; use the Claude Code tab or run `gnosys setup ides`. Since Cowork has no working directory of its own, it scopes memory by `projectRoot`. .cursor/mcp.json ```text { "mcpServers": { "gnosys": { "command": "gnosys-mcp", "args": [] } } } ``` Setup writes both project `.cursor/mcp.json` and user-level `~/.cursor/mcp.json`. terminal ```text $ claude mcp add -s user gnosys -- gnosys-mcp ``` Also registers Claude Desktop when you run `gnosys setup ides` → Claude Code. terminal ```text $ codex mcp add gnosys -- gnosys-mcp ``` Codex stores MCP in its CLI registry — hand-written `[mcp.gnosys]` TOML blocks are not recognized. Verify with `codex mcp list`. ~/.gemini/settings.json ```text { "mcpServers": { "gnosys": { "command": "gnosys-mcp", "args": [] } } } ``` ~/.gemini/antigravity/mcp_config.json ```text { "mcpServers": { "gnosys": { "command": "gnosys-mcp", "args": [] } } } ``` ~/.grok/config.toml ```text [mcp_servers.gnosys] command = "gnosys-mcp" args = [] startup_timeout_sec = 90 ``` Grok Build reads `[mcp_servers.gnosys]` (not `[mcp.gnosys]`). `startup_timeout_sec = 90` gives gnosys room on a cold start. opencode.json ```text { "mcp": { "gnosys": { "type": "local", "command": ["gnosys-mcp"] } } } ``` ### 2. Agent Rules — generated from your installed version `gnosys init` detects supported IDEs and writes the current rules and hooks. Use `gnosys sync --target all` after upgrading or changing preferences. The generated rules use `gnosys_discover` before work and `gnosys_add_structured` for deterministic writes. Gnosys intentionally does not publish hand-copied rule templates here, so the installed generator remains the source of truth. 1 ### Install & setup (once per machine) `npm install -g gnosys` then `gnosys setup` — LLM provider, API keys, and MCP wiring for Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI, Antigravity, and Grok Build via `gnosys-mcp`. 2 ### Initialize each project `gnosys init` registers the project, creates `.gnosys/gnosys.json`, writes agent rules/hooks for your IDE, and wires MCP for detected project-level tools. 3 ### Refresh rules (optional) `gnosys sync --target all` injects preferences and project conventions into `CLAUDE.md`, `.cursor/rules/gnosys.mdc`, or `.codex/gnosys.md`. Use `--global` for `~/.claude/CLAUDE.md`. 4 ### Your agent remembers Decisions, architecture choices, conventions, requirements — persisted in the central brain and discoverable across sessions. Architecture ## No black boxes SQLite is the sole source of truth. Dream Mode consolidates knowledge while you sleep. Export to Obsidian-compatible markdown anytime with one command. AI Agents Claude, Cursor, Windsurf, or any MCP client ⬢ Gnosys MCP Server Core toolset by default, full set on demand over stdio or HTTP projectRoot Audit Log Operation history on-demand export tracked gnosys.db FTS5 + embeddings WAL mode · source of truth SQLite core Dream Mode Idle-time consolidation: decay · critique · summarize Obsidian One-command export browse · search · graph export bridge ## Give your agents a memory Open source, MIT licensed. Built for developers who want their AI to remember what matters. [Get Started](https://github.com/proticom/gnosys) [Read the Docs](/docs) --- # Grok Bot + Gnosys — Persistent Memory for Multi-Agent Teams Source: https://gnosys.ai/grok-bot Grok Bot Integration # Persistent memory for multi-agent Grok Bot teams One dedicated Grok Bot seat runs local gnosys so your team never blocks on the CLI. Shared SQLite brain, project-scoped memory, and SendToAgent messaging keep every agent in sync. [Get Started](#setup) [Read Full Docs](/docs) Architecture ## How it works One Grok Bot seat named "Gnosys" runs the CLI directly. Sibling Grok Bots message that seat through SendToAgent for RECALL, QUERY, SAVE, and REINFORCE operations. No MCP attachment is required on the Grok Bot computer. Sibling Grok Bots Code, debug, docs Gnosys Grok Bot Seat Runs `gnosys` via Shell dedicated operator ~/.gnosys/gnosys.db SQLite brain on operator's computer local disk only **No cloud storage, no MCP on Grok Bot machines** The live database stays on the operator's local disk. Do not put it on iCloud, Dropbox, or SMB. Sibling Grok Bots never attach gnosys-mcp directly; they message the dedicated seat instead. Installation ## Set up in three steps Install gnosys, initialize your first project, and configure the dedicated Grok Bot seat. Bare install: the packaged Gnosys bot ships with skill gnosys-bot-operating-system only. 1 ### Install gnosys (once per machine) Requires Node.js ^22.16.0 or >=24.0.0. Install globally, then optionally configure LLM providers for advanced features. ```text npm install -g gnosys gnosys setup which gnosys && gnosys --version ``` **Optional:** `gnosys setup` configures LLM providers, API keys, and IDE integrations. MCP features work without a provider; configure one only for synthesis or multimodal tasks. 2 ### Initialize your first project Navigate to your project directory (or your Grok Bot working folder) and register it with gnosys. ```text cd "/absolute/path/to/project" gnosys init ``` Or specify the directory and name explicitly: ```text gnosys init -d "/abs/path" -n "Project Name" ``` **Recommended first project:** Your Grok Bot ops folder or working directory, named "Grok Bot". 3 ### Bootstrap the Gnosys Grok Bot seat Install or share the packaged Gnosys bot and note its current agent ID. Confirm the CLI and brain are accessible, then update sibling Grok Bots to message this seat. - Install/share the Gnosys bot; note its **current** agent ID (never a stale template ID) - Confirm CLI + brain; init your ops project - 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`) - Optional: migrate that install's own agent memories only; never another operator's data; skip secrets - 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:** memory 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. Benefits ## Why this pattern works Persistent shared memory, no CLI contention, project-scoped context, and bare-install simplicity. ### No CLI blocking One dedicated seat owns the gnosys CLI and brain. Sibling Grok Bots never compete for local access or wait on initialization. ### Project-scoped memory Memories are scoped to registered projects in the central SQLite DB. FTS5 keyword search and optional embeddings keep context relevant. ### SendToAgent coordination Sibling agents send RECALL, QUERY, SAVE, and REINFORCE messages to the Gnosys seat. No MCP attachment or gnosys CLI required on sibling machines. ### Local-first data The live SQLite database stays on the operator's local disk. No cloud storage concurrency, no iCloud/Dropbox corruption risk. ### Bare install The packaged Gnosys bot ships with skill gnosys-bot-operating-system only. No prior memories, no stale project context, no operator-specific paths. ### Author + tag tracking Each write includes author and tags {"agent":"SeatName"}. Trace who contributed what, filter by seat, and manage multi-agent knowledge. ## Ready to give your Grok Bot team a shared brain? Install gnosys on your machine, init your ops project, and bootstrap the dedicated Gnosys seat. Open source, MIT licensed, local-first. [Get Started](https://github.com/proticom/gnosys) [Full Documentation](/docs) --- # Gnosys token savings | Costs, estimates, and break-even Source: https://gnosys.ai/token-savings Token costs · OSS v7.0.0 · 25 October 2026 Dated snapshot: token costs measured against OSS v7.0.0 on 25 October 2026; not refreshed for later releases. # When Gnosys saves tokens. And when it does not. Our estimate: Gnosys can save tokens when it replaces a large, always-loaded memory file and you retrieve only what a task needs. Below break-even, it likely adds context. That is about 6k tokens with core loaded eagerly, or about 4k with verified tool deferral. Under about 2.5k, it adds context even with deferral and a single retrieval. [See the break-even estimates](#break-even) [Measure your workflow](#measure) TL;DR · Estimated tradeoff ## Selective memory still has a fixed cost. The core toolset is about 4.4k tokens before retrieval. In the model below, one or two targeted retrievals put break-even at about 5.9–7.4k tokens of replaced memory. A small index with selective file reads is already a lean baseline. [[1]](#source-toolsets) Always-loaded fileAll memory enters context M tokens ↔ Gnosys tools + retrievalSchemas plus the selected memory S + k × r tokens Compare the memory you actually load today. A full conversation transcript is a different baseline. This model compares context size, not total billed usage. Dated snapshot · Approximate tokens ## The tool schemas count too. Tool counts are documented and verified in source. Payload sizes are the character length of the tools/list JSON array. Token figures are approximations at about 4 characters per token, not tokenizer measurements. This is the fixed cost when a client loads all schemas in the selected tier. [[1]](#source-toolsets) Measured schema payloads, before any memory is retrieved. Tier sizes measured for Gnosys 7.0.0. | Starting tier | Tools | Payload | Approx. tokens | core (default) | 19 | ~18k chars | ~4.4k | standard | 34 | ~29k chars | ~7.2k | full | 56 | ~44k chars | ~11.1k Deferred tool loading can lower the starting cost. Verify what your client actually loads. The deferred scenario below is an estimate, not a guarantee for Claude Desktop. Estimates · Context size model ## Does your memory exceed break-even? Gnosys uses less memory context in this simplified model when M is greater than S + k × r. We assume r ≈ 1.5k tokens for a retrieval plus a follow-up read. Per-call retrieval sizes use a rough 4 characters per token heuristic. They are not measured usage. M > S + k × r MAlways-loaded memory replaced SFixed tool-schema cost kRetrievals per session rTokens per retrieval + read Estimates with r ≈ 1.5k tokens; extra model turns and write costs are excluded | Scenario | S | k | S + k × r | Saves context if M exceeds about | Core, light use | 4.4k | 1 | ~5.9k | ~6k tokens | Core, typical use | 4.4k | 2 | ~7.4k | ~7k tokens | Core, heavy use | 4.4k | 4 | ~10.4k | ~10k tokens | Deferred tools, typical use | ~1.0k | 2 | ~4.0k | ~4k tokens | Full, typical use | 11.1k | 2 | ~14.1k | ~14k tokens **Context saved is not the same as money saved.** This model leaves out tool-call output, repeated input across model turns, cache reads and writes, memory writes, and any external provider calls. Include those costs in your A/B run. No dollar savings are claimed here. Estimated fit ## Your baseline decides the result. ### Likely to save tokens - You replace a memory file larger than about 6–7k tokens and make one or two targeted retrievals. - Most tasks use a small part of your stored memory. - You keep the starting toolset small and limit repeated searches. ### Likely to add tokens - Your always-loaded memory is below break-even: about 6k tokens with core loaded eagerly, or about 4k with verified deferral. Under about 2.5k, it adds context in every scenario here. - You already use a small index with selective file reads. - The agent searches repeatedly, retrieves duplicates, or reads long memories in full. - You load the full tier for a task that only needs core retrieval. Recall defaults are verified in source: `maxMemories: 8`, `aggressive: true`, and `minRelevance: 0.4`. Recall formatting truncates each body snippet to 250 characters. Aggressive mode keeps the top three results before applying the relevance floor to the rest. These limits bound snippets, not every possible retrieval. `gnosys_read` returns a full memory. [[2]](#source-recall) Estimated search-type output is about 0.6–1.4k tokens per call; an atomic `gnosys_read` may add about 150–600 tokens. Titles, metadata, result count, and body length change those sizes. A long read can exceed that range. Configuration tips ## Start small. Retrieve with a purpose. ### Start on core and keep the tool list stable. Set the starting tier in your MCP server environment. Agents can still switch with `gnosys_toolset`, so instruct them to keep core for the session. If a task needs a larger tier, choose it at startup. [[1]](#source-toolsets) ```text "env": { "GNOSYS_MCP_TOOLSET": "core" } ``` Avoid mid-session escalation. Tool-list changes can invalidate a client's prompt cache. Verify cache behavior in your own usage logs. ### Verify deferral and keep the pointer file lean. Use deferred tools where your client supports them. Check the loaded schemas rather than assuming deferral works. Keep `CLAUDE.md` to a short pointer with identity, scope, and retrieval instructions. Review generated sync blocks so you do not load the same memory twice. ### Discover first. Read only what you need. Use `gnosys_discover` for metadata, with a small result limit such as 5–8. Then use `gnosys_read` for the one or two memories the task needs. Keep memories atomic and remove stale duplicates through your normal maintenance workflow. A/B protocol · Measure before switching ## Compare equal tasks and equal quality. Use 10–20 representative tasks with identical prompts, model, and settings. Record the client version, starting tier, and whether tool deferral is active. Control session length and cache conditions in both arms. Use the same information in each arm | Arm | Memory setup | Purpose | A · Baseline | Current markdown memory, no Gnosys | Measure what you use today | B · Core | Lean pointer file + Gnosys core | Include schema and retrieval overhead | C · Optional | Same as B, with verified tool deferral | Measure your client's deferred path 1 ### Record starting context. In Claude Code, inspect `/context` for tool schemas and memory-file usage. For exact schema counts, use your model provider's token-counting tool. 2 ### Record the complete session. Capture input, cache creation, cache read, and output tokens. Count memory calls and repeated searches. Include any separate provider usage for synthesis, embeddings, or maintenance. Record elapsed time too. 3 ### Check the answer, then compare. Score correct recall and completed tasks. Compare median total usage at equal or better quality. For a cost comparison, apply your provider's current rates to each token category. A smaller starting context alone does not prove a saving. Caveats and sources ## What is verified. What is estimated. Verified here means checked against our product docs or source, not independently benchmarked. Retrieval sizes, deferred costs, and break-even thresholds are estimates. This page does not provide an independent Gnosys token-usage benchmark. **Gnosys does not track cumulative tokens, dollars, or budgets.** Use your client and provider usage records. Gnosys does not enforce a spend budget. Configured synthesis and LLM-backed maintenance can add provider costs. [[3]](#source-cost) The phrase "Zero Context Bloat" is not a universal guarantee. Tool schemas and retrieved content use context. Client deferral, caching, repeated calls, and task quality determine the measured result. - [MCP toolset tiers](https://github.com/proticom/gnosys/blob/v7.0.0/docs/mcp-toolsets.md). Our documentation for tier counts, starting-tier configuration, and runtime switching. Payload character counts above were measured from tools/list on this date. - [Recall source](https://github.com/proticom/gnosys/blob/v7.0.0/src/lib/recall.ts). Verified defaults and the 250-character snippet limit. [Product documentation](/docs) describes retrieval tools. - [Cost and limits](https://github.com/proticom/gnosys/blob/v7.0.0/docs/cost-and-limits.md). No cumulative token or dollar tracking, and no enforced spend budget. [Read the docs](/docs) [Inspect the source](https://github.com/proticom/gnosys) --- # Web Knowledge Base Source: https://gnosys.ai/web-knowledge-base.md # Web Knowledge Base Guide A comprehensive guide to using Gnosys as a serverless-friendly knowledge backend for website chatbots. ## Concept Gnosys uses SQLite as the source of truth for its local memory system. Ephemeral serverless runtimes should not carry that live database, so the Web Knowledge Base pre-computes deployable artifacts at build time: 1. **Generated Markdown content files** — build artifacts with YAML frontmatter, not the canonical Gnosys memory store 2. **A JSON search index** — an inverted index generated at build time, deployed as a static asset At runtime, your chatbot loads the index into memory and searches it. The search path needs no live database or external search service. ## Setup Walkthrough ### Prerequisites - Node.js `^22.16.0 || >=24.0.0` - A website with content to index (sitemap, local files, or URL list) - `npm install -g gnosys` ### Step 1: Initialize ```bash cd your-nextjs-site gnosys init # registers the project and writes project identity/config gnosys web init # creates knowledge/ dir, adds web config to gnosys.json ``` ### Step 2: Configure Edit `gnosys.json` in your `.gnosys/` directory: ```json { "web": { "source": "sitemap", "sitemapUrl": "https://yoursite.com/sitemap.xml", "outputDir": "./knowledge", "exclude": ["/api", "/admin", "/_next", "/login"], "categories": { "/blog/*": "blog", "/docs/*": "documentation", "/services/*": "services", "/products/*": "products", "/about*": "company", "/faq*": "faq" }, "llmEnrich": true, "prune": false, "concurrency": 3, "crawlDelayMs": 200 } } ``` ### Step 3: Build ```bash gnosys web build ``` This crawls your site, converts pages to markdown with structured frontmatter, and generates the search index. The output looks like: ``` knowledge/ blog/ building-in-public.md ai-readiness-assessment.md services/ agentic-automation.md products/ mavenn.md company/ about.md faqs.md gnosys-index.json ``` ### Semantic search (optional) Lexical search remains the default. To add hybrid semantic search, opt in during the build: ```bash gnosys web build --embeddings openai ``` This emits `knowledge/gnosys-vectors.json` beside the regular index. The vector file stores int8-quantized document vectors plus the embedding model and dimensions, so the deployed route can verify it is embedding queries with the same model. At runtime, the route embeds only the user's query, loads the static vectors file, and passes the query vector to `search()`: ```typescript const queryModel = 'text-embedding-3-small' const queryVector = await embedQuery(message, queryModel) const results = search(index, message, { limit: 6, vectors, queryVector, expectedModel: queryModel, }) ``` `search()` automatically uses lexical-only ranking when vector inputs are absent or when the vector model or dimensions do not match. The `gnosys/web` module does **not** call an embedding API, so your route must catch vector-file loading failures and query-embedding failures, then call `search()` without vector inputs. A missing API key or embedding API error falls back only when the integration implements that error handling. No vector database is required, and the `gnosys/web` runtime search module has no external runtime dependencies. Confirm compatibility with your specific serverless or edge platform. Embedding providers are `openai`, `voyage`, and `local`. Use `--embed-model ` to override the default model. The `local` provider uses the existing transformers.js MiniLM path, which is useful at build time but is not the edge-safe default for runtime query embedding. When LLM enrichment is enabled, Gnosys also writes concept expansions into `gnosys-index.json` so related terms can improve recall without any runtime LLM key. Use `--no-expansions` to skip that generation. ### Step 4: Integrate ```typescript import { loadIndex, search } from 'gnosys/web' import { readFileSync } from 'fs' import { join } from 'path' const index = loadIndex(join(process.cwd(), 'knowledge', 'gnosys-index.json')) export async function POST(req: Request) { const { message } = await req.json() const results = search(index, message, { limit: 6 }) const context = results.map(r => readFileSync(join(process.cwd(), 'knowledge', r.document.path), 'utf8') ).join('\n\n---\n\n') // Use any LLM provider const response = await anthropic.messages.create({ model: 'claude-sonnet-4-20250514', system: `Answer using ONLY the provided context.\n\nContext:\n${context}`, messages: [{ role: 'user', content: message }], }) return Response.json({ reply: response.content[0].text }) } ``` ### Step 5: Automate Add to your `package.json`: ```json { "scripts": { "postbuild": "gnosys web build" } } ``` Commit the `knowledge/` directory to git. It deploys with your app. ## Source Types ### Sitemap (default) Fetches `sitemap.xml`, processes each URL. Handles sitemap index files (``) that contain multiple child sitemaps. ```json { "web": { "source": "sitemap", "sitemapUrl": "https://yoursite.com/sitemap.xml" } } ``` ### Directory Reads local content files (`.md`, `.mdx`, `.html`) from a specified directory. Useful for static site generators where content is already on disk. ```json { "web": { "source": "directory", "contentDir": "./content" } } ``` MDX files are supported — JSX components and import statements are automatically stripped, preserving the markdown content. ### URL List Processes a manually specified list of URLs. Useful for selective ingestion. ```json { "web": { "source": "urls", "urls": [ "https://yoursite.com/blog/important-post", "https://yoursite.com/services/main-offering" ] } } ``` ## Category Mapping URL patterns map to category directories using simple glob syntax: ```json { "categories": { "/blog/*": "blog", "/docs/*": "documentation", "/services/*": "services", "/about*": "company" } } ``` - `/blog/*` matches `/blog/any-slug` - `/about*` matches `/about`, `/about-us`, `/about/team` - Unmatched URLs default to `general` Categories determine the subdirectory in `knowledge/` where files are written, keeping the directory human-browsable. ## LLM vs Structured Mode ### LLM Mode (default when a provider is configured) Uses the existing Gnosys LLM provider abstraction to generate rich frontmatter: - Precise titles - Intelligent category assignment - Domain-specific tags - High-quality relevance keyword clouds (15-25 terms) Uses the `structuring` task model routing, so `taskModels.structuring` in your config controls which provider/model is used. ### Structured Mode (no LLM fallback) When no LLM provider is configured, Gnosys falls back to algorithmic structuring: - **Title**: Extracted from `

`, ``, or filename - **Category**: Inferred from URL path patterns - **Tags**: Extracted from `<meta name="keywords">` and URL segments - **Relevance keywords**: Generated via TF-IDF across the entire corpus Force structured mode with `--no-llm`: ```bash gnosys web build --no-llm ``` Quality is lower but fully functional. No API costs. ## Build Pipeline Integration ### Next.js ```json { "scripts": { "postbuild": "gnosys web build" } } ``` ### Nuxt ```json { "scripts": { "postbuild": "gnosys web build" } } ``` ### Astro ```json { "scripts": { "postbuild": "gnosys web build" } } ``` ### Any Node.js framework The pattern is the same: run `gnosys web build` after your framework build completes. The knowledge files and index are static assets that deploy alongside your app. ## Search Tuning Search quality depends on the `relevance` field in each knowledge file's frontmatter. This is a keyword cloud that powers discovery: ```yaml relevance: 'AI chatbot automation workflow integration enterprise deployment scaling' ``` ### Tips for better results - **LLM mode** generates the best relevance keywords automatically - In structured mode, TF-IDF selects distinctive terms from each document - You can manually edit any knowledge file's `relevance` field — it's just markdown - After editing, rebuild the index: `gnosys web build-index` - Tags in frontmatter are weighted 2x, relevance keywords 3x, title 2x, content 1x ### Search API ```typescript import { loadIndex, search, getDocument, listDocuments } from 'gnosys/web' // Search with options const results = search(index, 'AI automation', { limit: 6, // max results (default: 6) minScore: 0.1, // score threshold (default: 0.1) category: 'blog', // filter by category tags: ['ai'], // filter by tags (any match) boostRecent: true, // boost recent documents }) // Get a specific document const doc = getDocument(index, 'blog-001') // List all documents with filters const blogDocs = listDocuments(index, { category: 'blog', status: 'active' }) ``` ## GEO Strategy GEO (Generative Engine Optimization) makes your content discoverable by AI systems. ### Serving knowledge files to crawlers The `knowledge/` directory contains well-structured markdown with YAML frontmatter. AI crawlers can extract structured metadata directly: ```yaml --- title: 'Agentic Automation Services' category: services tags: domain: [automation, ai, workflow] type: [service] relevance: 'automation agentic workflow process integration enterprise' --- ``` ### llms.txt integration Add a pointer to your knowledge directory in `llms.txt`: ``` # Knowledge Base knowledge/gnosys-index.json knowledge/blog/ knowledge/services/ knowledge/products/ ``` ## Manual Editing Knowledge files are standard markdown with YAML frontmatter. You can: - Edit titles, tags, relevance keywords, or content directly - Add new knowledge files by hand (follow the frontmatter format) - Remove files you don't want indexed - After any manual changes, rebuild the index: `gnosys web build-index` ## Troubleshooting ### Empty search results - Check that `gnosys-index.json` exists in your knowledge directory - Verify the index has documents: `gnosys web status` - Check that your query terms appear in the relevance keywords, tags, or content - Try lowering `minScore` in search options ### Stale index If you've edited knowledge files manually, rebuild: `gnosys web build-index` ### Build failures - Ensure `gnosys.json` has a `web` section: run `gnosys web init` - For sitemap source: verify the URL is accessible - For directory source: verify the path exists and contains `.md`/`.html` files - Check network connectivity for remote URLs ### Large sites For sites with 1000+ pages: - Use `exclude` patterns to skip unnecessary pages - Increase `concurrency` (max 10) for faster ingestion - The JSON index scales well — 200 documents produces ~100KB index ### Native module errors with `gnosys/web` The `gnosys/web` subpath must not pull in native dependencies. If you see `better-sqlite3` errors when importing `gnosys/web`, this is a bug — the import chain should be isolated. Report it. --- # Privacy Policy — Gnosys Source: https://gnosys.ai/privacy Privacy Policy # Your memories stay under your control. Effective date: 5 October 2026 · Version 1.3 ## Who we are Gnosys and gnosys.ai are operated by: **JAMAEDGE Group LLC** (doing business as **Proticom**) 16835 Algonquin St, Suite 205 Huntington Beach, CA 92649, United States Privacy contact: [privacy@gnosys.ai](mailto:privacy@gnosys.ai) **EU/UK Representative (Art. 27 GDPR / UK GDPR):** not currently appointed. Contact us at [privacy@gnosys.ai](mailto:privacy@gnosys.ai); we will appoint a representative if and when applicable law requires one. ## The one-paragraph version Gnosys is **local-first, open-source software**. In the normal OSS setup, your memories live in a SQLite database **on your own computer** (`~/.gnosys/gnosys.db`); gnosys.ai does not host that database, a memory API, or an MCP endpoint. Content leaves your machine only when you choose a feature or provider that requires a network request. This website runs **no advertising or behavioral analytics**; the optional Agent Profile claim flow uses one short-lived security cookie, and its hosting, third-party assets, and limited OAuth service process the operational data described below. If you use the **Ask Gnosys chat** on this site, the text you type is sent to **OpenAI** to generate the answer. We do not store your chat messages. ## 1. The gnosys.ai website | What | Details | Website use | No end-user account, advertising, or behavioral analytics. The site serves documentation, agent-discovery files, a read-only project-metadata API, and a limited Agent Profile OAuth service. It does **not** host Gnosys memories or an MCP server. | Cookies and local preferences | We use no advertising, analytics, or cross-site tracking cookies. Theme and page-view preferences may be stored in your browser's localStorage. The chat conversation is kept only in the open page and is cleared when you reload or leave it. After a successful optional Agent Profile claim, we set one Secure, HttpOnly, SameSite=Lax consent cookie for 30 minutes so that browser can complete PKCE authorization (see the [Cookie Policy](/cookies)). | Hosting and request logs | **Cloudflare** serves the site and Worker endpoints. Cloudflare processes standard request data such as IP address, request URL, user agent, timestamps, and security signals in its infrastructure and logs. We may use limited operational logs to secure and troubleshoot the service; we do not use them for advertising. | Third-party assets | Pages request fonts from **Google Fonts**. Google receives standard connection data, including your IP address and user agent, under their own privacy terms. No advertising pixels or social-media embeds are used. | Ask Gnosys chat | The optional chat on this site answers questions about Gnosys. When you send a message, your text and the earlier messages of the same conversation (up to the last 10 messages, each up to 2,000 characters) are sent through our Cloudflare Worker to **OpenAI**, together with excerpts from the public Gnosys documentation, so that an OpenAI model can generate the answer. Do not type personal or confidential information. We do not log, store, or reuse the content of your messages or the answers. To prevent abuse, Cloudflare counts requests per IP address for one minute to enforce a rate limit. OpenAI processes the text under its API terms: per OpenAI's API data policy, API data is not used to train OpenAI models by default, and OpenAI may keep abuse-monitoring logs for up to 30 days unless the law requires longer. Answers are generated by AI and may be wrong; check them against the documentation. | Agent Profile OAuth service | When this optional service is used, we process the agent-supplied display name and redirect URIs, an anonymous registration identifier and status, issue/expiry timestamps, requested scope, and claim/revocation/security state. Claim tokens, user codes, authorization codes, and network-derived rate-limit identifiers are stored only as keyed hashes where persistence is required. Unclaimed registrations expire after 24 hours; claimed registrations after at most 30 days; shorter-lived credential and security records are removed after their operational window. The service never accepts or stores Gnosys memory content. Legal basis (where GDPR-type laws apply): our legitimate interests in delivering and securing the website and preventing abuse (Art. 6(1)(f)); when you request an Agent Profile registration or send a message in the Ask Gnosys chat, processing is also necessary to provide that requested function (Art. 6(1)(b), where applicable). We do not sell this data or use it for targeted advertising. ## 2. The Gnosys open-source software (what happens on *your* machine) When you run Gnosys, **you are the data controller** of everything you store in it. We are not a controller or processor for that data — it never reaches us. **Data the software stores locally, under your control:** | Category | Where | Retention | Memories you write (free text — may include any personal data you choose to record) | `~/.gnosys/gnosys.db` on your device | Until you archive or supersede them, remove individual records with your own database tools, or remove the database. Gnosys does not currently advertise a general-purpose memory-delete command. | Tags, project names, file paths | Local database | Same | Attachments (images/small files ≤10 MB) | Local database | Same | Search embeddings | Stored locally or in static output. Local embeddings are computed on-device; OpenAI or Voyage embedding modes send the applicable source or query text to that provider. | Same | Audit log of tool operations | Local database | Same | Hostname / machine ID (for your own multi-machine sync) | Local database + local config | Same **Network connections the software may make, depending on the features and configuration you choose:** - **Optional providers and endpoints you configure.** Cloud options include Anthropic, OpenAI, Groq, xAI, Mistral, OpenRouter, Voyage embeddings, and custom OpenAI-compatible endpoints. Applicable prompts, retrieved context, documents, images, audio, or queries are sent **under your own account and the provider's terms**, only for the features you invoke. Ollama, LM Studio, local Whisper, and local embeddings provide local alternatives for supported workflows, but not every AI-specific feature has a provider-free equivalent. - **Local model downloads.** A local embedding or transcription mode may download model weights from a package or model CDN such as Hugging Face. User content is not uploaded as part of the model download; the downloaded model then runs locally. - **Package installation/updates** via the npm registry (standard npm behavior). - **Web Knowledge Base requests.** Gnosys crawls the sites you direct it to. OpenAI or Voyage build/runtime embedding modes also send applicable document or query text to the selected provider; callers of `gnosys/web` control runtime query embedding and fallback behavior. **There is no telemetry, analytics, crash reporting, or any other "phone home" in the software.** **Web Knowledge Base:** if you use `gnosys web` to index a website, the software crawls the site *you* point it at and writes static files into *your* project. You are responsible for the content of sites you crawl and for configuring any remote embedding provider used during builds or runtime queries. ## 3. Sub-processors and international transfers gnosys.ai does not process the memories in your local OSS database. The following parties may process website operational data, asset requests, or content you deliberately route to a provider: | Party | Role | Personal data | Safeguard | Cloudflare, Inc. (US/global network) | Website/Worker and D1 hosting, security, limited Agent Profile state | Request metadata and IP addresses; agent-supplied display name and redirect URIs; limited registration/security state; hashed claim, authorization-code, and rate-limit identifiers | Cloudflare's contractual, privacy, and security controls | OpenAI, L.L.C. (US) | Generates answers for the Ask Gnosys chat | The chat text you send and excerpts of public documentation; standard request data from our Worker (not your IP address) | OpenAI's API terms and data-usage policy (no training on API data by default; abuse-monitoring logs up to 30 days) | Google LLC (US/global network) | Google Fonts delivery | Standard asset-request data such as IP address and user agent | Google's privacy and security controls | GitHub, Inc. (US) | Code, issue, and release distribution when you follow repository links | Data GitHub receives from your visit or account | Your interaction with GitHub under its terms | Hugging Face and other model/package CDNs | Optional local model-weight downloads | Standard request data such as IP address | The provider's terms; no Gnosys memory content is needed for the download | AI and embedding providers you configure | Only for tasks you deliberately route to them | Prompts, context, documents, media, or queries required for the selected task | Your agreement with the provider A separately contracted **Gnosys Enterprise** hosted offering exists for organizations; it is governed by its own agreement and data-processing addendum (with SCCs Module 2 and transfer assessments where applicable), not by this policy. *Status: DPA/SCC/TIA documentation in progress; completed before enterprise onboarding of EU/UK customers.* ## 4. Geographic note (EU/UK) Our hosted enterprise offering is not currently offered to customers in the EU or UK. The OSS code is available worldwide. Website requests and optional Agent Profile registrations may be processed by Cloudflare and the asset providers described above, including on global infrastructure. If you use the Ask Gnosys chat, your messages are transferred to OpenAI in the United States; provider-backed OSS features are governed by the provider you choose. ## 5. Your rights For website visitors in jurisdictions with data-subject rights (including GDPR, UK GDPR, and CCPA/CPRA), contact [privacy@gnosys.ai](mailto:privacy@gnosys.ai) to request access, correction, deletion, restriction, portability, or objection where applicable. Agent Profile credentials can also be revoked through the documented revocation flow. We do not sell personal information or share it for cross-context behavioral advertising. For data inside your local Gnosys install, you control the database directly; we cannot access or act on that local data. ## 6. AI transparency (EU AI Act) Gnosys is a memory/retrieval developer tool, not an AI model. Core structured-memory workflows and lexical search can run without an AI provider. Features such as answer synthesis, vision ingestion, and some enrichment workflows require a compatible model; local provider options are available only where documented. No Annex III high-risk use is intended or supported. The Ask Gnosys chat on this website is an AI assistant: its answers are generated by an OpenAI language model from our public documentation, and the chat window says so. ## 7. Children Gnosys is a developer tool and this site is not directed at children. We do not knowingly solicit children's personal information; contact us if you believe a child has submitted Agent Profile or other website data. ## 8. Changes We will post changes here with a new version number and effective date. Material changes will be highlighted in the repository changelog.