gnosys MCP server
Commit Nov 13, 2026Provides AI agents with persistent, searchable memory across sessions and projects using a local SQLite database.
Also known as proticom/gnosys
- Stars
- 5
- Tools
- 60
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is gnosys MCP?
gnosys provides AI agents with persistent, searchable memory across sessions and projects using a local SQLite database. It exposes 60 tools, such as gnosys, gnosys-mcp, gnosys_discover.
Summary generated from the project's README
About gnosys MCP server
Gnosys provides AI agents with a persistent memory system that functions across different sessions, projects, and machines. It uses a local SQLite database located at ~/.gnosys/gnosys.db to store information, ensuring sub-10ms read speeds without requiring external services or vector databases. This setup allows developers to maintain a unified brain for their AI tools, ranging from project-specific notes to global user knowledge.
The server operates as a CLI and a full MCP server that integrates with clients like Claude Desktop, Cursor, and Gemini CLI. It exposes over 50 tools, including gnosys_add_structured for efficient memory storage and gnosys_hybrid_search for combining keyword and semantic retrieval. Users can manage their data through the gnosys CLI, which supports initializing projects, adding memories, and even exporting the entire database into an Obsidian vault.
To handle complex information, the system includes a Dream Mode for idle-time consolidation and relationship discovery. It also supports multi-machine synchronization and can ingest various file types, including PDFs, images, and audio, through the gnosys_ingest_file tool.
What you can do with it
- 1Maintain project contextAn AI agent can store specific technical decisions to prevent losing context between different coding sessions.
- 2Convert memory to human-readable notesYou can transform your AI's stored knowledge into a structured Obsidian vault for manual review.
- 3Automate memory organizationAgents can use structured tools to add information without needing to call an LLM for processing.
Written from the project's README. Every use case is checked against a quote from it.
gnosys MCP tools 60
Detected from the READMEgnosysgnosys-mcpgnosys_discovergnosys_readgnosys_searchgnosys_listgnosys_add_structuredgnosys_addgnosys_tagsgnosys_tags_addgnosys_reinforcegnosys_init
Show all 60 toolsShow fewer tools
gnosys_migrategnosys_updategnosys_stalegnosys_commit_contextgnosys_historygnosys_lensgnosys_timelinegnosys_statsgnosys_linksgnosys_graphgnosys_bootstrapgnosys_importgnosys_hybrid_searchgnosys_semantic_searchgnosys_reindexgnosys_askgnosys_maintaingnosys_dearchivegnosys_reindex_graphgnosys_dreamgnosys_exportgnosys_dashboardgnosys_storesgnosys_recallgnosys_auditgnosys_preference_setgnosys_preference_getgnosys_preference_deletegnosys_syncgnosys_federated_searchgnosys_detect_ambiguitygnosys_briefinggnosys_portfoliognosys_remote_statusgnosys_remote_pushgnosys_remote_pullgnosys_remote_resolvegnosys_update_statusgnosys_working_setgnosys_ingest_filegnosys_attachgnosys_get_attachmentgnosys_tracegnosys_reflectgnosys_traversegnosys_toolsetstandardfull
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableproticom/gnosys is public and reachablegithub.com/proticom/gnosys ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/proticom/gnosys ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model60 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubGnosys — One Brain. Zero Context Bloat.
Gnosys gives AI agents persistent memory that survives across sessions, projects, and machines.
The central brain is a single SQLite database at ~/.gnosys/gnosys.db with sub-10ms reads — no vector DBs, no black boxes, no external services. Federated search ranks results across project, user, and global scopes. It runs as a CLI and as a full MCP server that drops straight into Claude Code, Claude Desktop (Chat / Cowork / Code), Cursor, Codex, Gemini CLI, Antigravity, Grok Build, or any MCP client. When you want a human-readable view, gnosys export regenerates a full Obsidian vault on demand.
Install
Requires Node.js ^22.16.0 || >=24.0.0. FTS5 requires this floor. Node 23.x is unsupported. SQLite uses built-in
node:sqlite. No native SQLite dependency or rebuild is needed when switching supported Node versions.
npm install -g gnosys
gnosys setup # configures provider, API key, and your IDE/agent
Optional local embeddings. Gnosys auto-installs @huggingface/transformers. If it cannot install, use an external embedding API. SQLite does not need this package.
Quick start
gnosys setup ides # wire MCP into your IDEs (once)
cd your-project
gnosys init # register the project
gnosys add "We chose PostgreSQL over MySQL for JSON support"
gnosys recall "database selection" # what's relevant right now
That's the 60-second tour. Everything else lives on gnosys.ai.
What you get
- Central brain — one
~/.gnosys/gnosys.dbunifies every project (project / user / global scopes). Sub-10ms reads, SQLite as the sole source of truth. - Federated search — tier-boosted hybrid (FTS5 keyword + semantic) search across scopes, with recency and reinforcement.
- MCP server —
gnosys serveexposes 50+ memory tools to any MCP client. Sandbox-first runtime keeps context cost near zero. - Web Knowledge Base —
gnosys web buildturns any site into a searchable index for serverless chatbots, with optional build-time vectors for serverless-safe hybrid semantic search. Zero runtime deps. - Dream Mode — idle-time consolidation: confidence decay, summaries, relationship discovery. Never deletes — only suggests.
- Multi-machine sync — share your brain across machines; conflict detection with skip-and-flag resolution.
- Obsidian export —
gnosys exportregenerates a full vault with frontmatter,[[wikilinks]], and graph data.
MCP Tool Reference
All tools are exposed over stdio and HTTP transports. Many tools accept an optional projectRoot parameter to target a specific project store.
This package installs two binaries:
gnosys— the CLI.gnosys servestarts the MCP server (stdio by default,--transport httpfor the central-server topology).gnosys setup ideswiresgnosys-mcpinto your IDE/agent configs.gnosys-mcp— a direct alias for the MCP stdio server entry, installed withnpm install -g gnosys, for MCP clients that spawn the server binary directly. Equivalent tognosys serve. With npx, usenpx -y gnosys serve.
On stdio EOF, the server drains received requests, writes their responses, and
closes resources before exiting 0. Embedding flushes get at most 500 ms or one
third of the shutdown timeout; reindex or an embedding-enabled Dream run recovers
missing vectors. Cleanup errors or the 1500 ms shutdown backstop exit 1.
GNOSYS_SHUTDOWN_TIMEOUT_MS accepts plain decimal integers without whitespace
(100–60000 ms). Out-of-range integers and signed infinities warn and clamp to
the nearest bound; other formats warn and use 1500 ms. Both transports exit
130 for SIGINT and 143 for SIGTERM. The first signal during an EOF drain lets
requests finish and sets that exit status. Only a second actual signal forces
immediate resource cleanup and exits with its status. HTTP ignores stdin closure.
On a signal, HTTP rejects new requests and drains admitted POST responses before closing SSE streams.
Synchronous event-loop blocking (for example a long handler or SQLite call) defeats the shutdown bound/backstop; there is no watchdog process.
| Tool | Tier | Description |
|---|---|---|
gnosys_discover |
standard | Discover relevant memories by describing what you're working on. |
gnosys_read |
core | Read a specific memory. |
gnosys_search |
standard | Search memories by keyword across all stores. |
gnosys_list |
standard | List memories across all stores, optionally filtered by category, tag, or store layer. |
gnosys_add_structured |
core | Preferred for LLM agents. Add a memory with structured fields you supply (title, category, tags, content) — makes no server-side LLM call. |
gnosys_add |
full | Add a memory from raw text; the server's LLM structures it. For non-agent callers (scripts, cron) — agents should use gnosys_add_structured. |
gnosys_tags |
standard | List all tags in the registry, grouped by category. |
gnosys_tags_add |
full | Add a new tag to the registry. |
gnosys_reinforce |
core | Signal whether a memory was useful. |
gnosys_init |
core | Initialize Gnosys in a project directory. |
gnosys_migrate |
full | Migrate a Gnosys store (.gnosys/) from one directory to another. |
gnosys_update |
core | Update an existing memory's frontmatter and/or content. |
gnosys_stale |
full | Find memories that haven't been modified or reviewed within a given number of days. |
gnosys_commit_context |
full | Pre-compaction memory sweep. |
gnosys_history |
full | View audit history for a memory. |
gnosys_lens |
standard | Filtered view of memories. |
gnosys_timeline |
standard | View memory creation and modification activity over time. |
gnosys_stats |
standard | Summary statistics across all memories — totals by category, status, author, authority, average confidence, and date ranges. |
gnosys_links |
standard | Show wikilinks for a specific memory — outgoing [[links]] and backlinks from other memories. |
gnosys_graph |
standard | Show the full cross-reference graph across all memories. |
gnosys_bootstrap |
full | Batch-import existing documents from a directory into the memory store. |
gnosys_import |
full | Bulk import structured data (CSV, JSON, JSONL) into Gnosys memories. |
gnosys_hybrid_search |
core | Main search: keyword, semantic, or hybrid ranking with snippets and IDs. |
gnosys_semantic_search |
standard | Search memories using semantic similarity only (no keyword matching). |
gnosys_reindex |
full | Rebuild all semantic embeddings from every memory file. |
gnosys_ask |
standard | Ask a natural-language question and get a synthesized answer with citations from the entire vault. |
gnosys_maintain |
full | Run vault maintenance: detect duplicate memories, apply confidence decay, consolidate similar memories. |
gnosys_dearchive |
full | Force-dearchive memories from archive.db back to active. |
gnosys_reindex_graph |
full | Build or rebuild the wikilink graph (.gnosys/graph.json). |
gnosys_dream |
full | Run a Dream Mode cycle — idle-time consolidation that decays confidence, generates category summaries, discovers relationships, and creates review suggestions. |
gnosys_export |
full | Export gnosys.db to Obsidian-compatible vault — atomic Markdown files with YAML frontmatter, [[wikilinks]], category summaries, and relationship graph. |
gnosys_dashboard |
core | Show the Gnosys system dashboard: memory counts, maintenance health, graph stats, LLM provider status. |
gnosys_stores |
full | Debug tool — lists all detected Gnosys stores across registered projects, MCP workspace roots, cwd, and environment variables. |
gnosys_recall |
core | Fast memory recall — inject relevant memories as context. |
gnosys_audit |
full | View the audit trail of all memory operations (reads, writes, reinforcements, dearchives, maintenance). |
gnosys_preference_set |
core | Set a user preference. |
gnosys_preference_get |
core | Get a user preference by key, or list all preferences. |
gnosys_preference_delete |
standard | Delete a user preference by key. |
gnosys_sync |
full | Get the current user preferences + project conventions formatted as a GNOSYS:START/GNOSYS:END block. |
gnosys_federated_search |
standard | Search across scopes with boosts, memory IDs, status labels, and replacements before history. |
gnosys_detect_ambiguity |
full | Check if a query matches memories in multiple projects. |
gnosys_briefing |
core | Generate a project briefing — a summary of memory state, categories, recent activity, and top tags. |
gnosys_portfolio |
full | Portfolio dashboard — shows all registered projects with memory counts, categories, status snapshots, roadmap items, and recent activity. |
gnosys_remote_status |
full | Check the status of remote sync (multi-machine). |
gnosys_remote_push |
full | Push local memory changes to the remote (NAS) database. |
gnosys_remote_pull |
full | Pull remote memory changes to the local database. |
gnosys_remote_resolve |
full | Resolve a sync conflict by choosing which version to keep. |
gnosys_update_status |
standard | Get the prompt/template for writing a dashboard-compatible status memory for this project. |
gnosys_working_set |
standard | Get the implicit working set — recently modified memories for the current project. |
gnosys_ingest_file |
standard | Ingest a file (PDF, DOCX, TXT, MD, images via vision LLM, audio/video via Whisper transcription) into Gnosys memory. |
gnosys_attach |
standard | Attach a small binary file (logo, diagram, screenshot, small PDF) inline to a memory (~10MB limit; syncs machine-to-machine). |
gnosys_get_attachment |
standard | Retrieve the binary attachment stored on a memory (base64 bytes, or write to disk via outputPath). |
gnosys_trace |
standard | Trace a codebase directory and store procedural "how" memories with call-chain relationships. |
gnosys_reflect |
core | Record a real-world outcome against related memories, adjusting their confidence and linking them. |
gnosys_traverse |
core | Walk relationship chains from a memory id (BFS, depth-limited), optionally filtered by direction or relationship types. |
gnosys_toolset |
core | Inspect the tool catalog or switch the active tier. |
Toolset tiers
Tool descriptions and schemas consume agent context, so since v6.2.0 every session starts on the core tier and agents self-escalate in-session: calling gnosys_toolset without arguments lists what the higher tiers add, and gnosys_toolset {"set": "standard"|"full"} enables them at runtime (and "core" shrinks back). The switch emits notifications/tools/list_changed, so MCP clients pick up the new tools automatically.
| Tier | Tools | Contents |
|---|---|---|
core (default) |
14 | Main memory workflow, hybrid search, reflection, traversal, and tier switching |
standard |
33 | Core plus specialist search, tracing, browsing, attachments, and ingestion |
full |
56 | All tools, including freeform ingestion, maintenance, remote sync, and export |
GNOSYS_MCP_TOOLSET=core|standard|full overrides the starting tier (unknown values warn on stderr and fall back to core). The starting toolset and escalation hint are announced in the MCP server instructions. See docs/mcp-toolsets.md.
Documentation
| Full docs & guides | https://gnosys.ai |
| Complete CLI + MCP reference | https://gnosys.ai/guide.html |
| Changelog | CHANGELOG.md |
| Contributing | CONTRIBUTING.md |
| Security policy | SECURITY.md |
| Report a bug / request a feature | GitHub Issues |
License
gnosys MCP questions
What tools does gnosys MCP provide?
It exposes 60 tools, including gnosys, gnosys-mcp, gnosys_discover, gnosys_read, gnosys_search.
How is the memory stored?
The central brain is a single SQLite database located at ~/.gnosys/gnosys.db.
Can I export my memories to another application?
Yes, you can use the export command to regenerate a full Obsidian vault with wikilinks and graph data.
Does it require an external database or vector service?
No, it uses a local SQLite database and does not require external services or vector databases.
What are the Node.js requirements?
You need Node.js version 22.16.0 or higher, or version 24.0.0 or higher. Node 23.x is not supported.