gnosys

library5.11.4jsnpmunverified

Gnosys is a persistent memory system for AI agents, providing a central SQLite brain at ~/.gnosys/gnosys.db with sub-10ms reads. It integrates as a CLI and MCP server, supporting Claude, Cursor, Gemini CLI, and others. Version 5.11.4 requires Node.js >=20.12, ships TypeScript types, and is actively maintained. Key differentiators: no external vector databases, no black boxes, federated search across project/user/global scopes, Dream Mode for idle consolidation, Web Knowledge Base, and Obsidian export. The package is developed by Proticom.

ai-ml database

npm install gnosys

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GNOSYS

gnosys

ai-mljavascriptv5.11.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

gnosys (CLI)

✓ npx gnosys <command>

✗ Using global install without npx (may cause version conflicts)

The CLI is the primary interface; no programmatic API is exposed in this version.

gnosys-mcp (MCP server)

✓ gnosys-mcp

✗ Using require('gnosys-mcp') in Node.js (MCP server is a binary, not a module)

This binary is an alias for gnosys serve --transport stdio.

setup

✓ gnosys setup

✗ gnosys init (only registers a project; setup is required first)

setup configures provider, API key, and IDE/agent integration.

Install Gnosys globally, configure it, wire into IDEs, initialize a project, add a memory, recall it, and start a memory-aware chat.

npm install -g gnosys gnosys setup gnosys setup ides cd your-project gnosys init gnosys add "We chose PostgreSQL over MySQL for JSON support" gnosys recall "database selection" gnosys chat

Debug

Known issues

breakingGnosys 5.x requires Node.js >= 20.12; earlier Node versions are not supported.

fix

Upgrade Node.js to >=20.12.

affects: <5.0.0

deprecatedThe global scope flag --global in gnosys add is deprecated in favor of explicit scope parameter.

fix

Use --scope global instead of --global.

affects: >=5.0.0 <5.5.0

gotchaIf better-sqlite3 fails to install due to missing build tools, Gnosys will degrade gracefully but performance may suffer with fallback storage.

fix

Run npm install better-sqlite3 @huggingface/transformers or configure an external embedding API.

affects: >=5.0.0

gotchaMCP server over stdio: if the environment doesn't have the gnosys-mcp binary in PATH, the client may fail to connect.

fix

Ensure gnosys is installed globally (npm install -g gnosys) and that the global bin directory is in PATH.

affects: >=5.0.0

Errors

Common errors & fixes

Error: Cannot find module 'better-sqlite3'

Native SQLite binding failed to compile or is not installed.

fix

npm install better-sqlite3

gnosys: command not found

Global installation directory not in PATH.

fix

Add $(npm config get prefix)/bin to PATH, or use npx gnosys.

Error: EACCES: permission denied, mkdir '/root/.gnosys'

Running Gnosys as root without proper home directory.

fix

Run as a non-root user, or set HOME environment variable to a writable directory.

Upgrade

Version history

5.11.4latest on npm

Audit

Dependencies

better-sqlite3optionalSQLite engine for persistent storage

@huggingface/transformersoptionalLocal embeddings for semantic search

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/proticom/gnosys ↗

packagegnosys ↗

homepagehttps://gnosys.ai ↗