Open Source · MIT License

Persistent memory
for AI agents

Gnosys gives LLMs a centralized brain that survives across sessions and projects. 50+ MCP tools, 8 LLM providers, federated search, Web Knowledge Base for serverless chatbots, sandbox runtime, process tracing, and Dream Mode consolidation. Works with any MCP client.

macOS Linux Windows

View on GitHub See How It Works

$ npm install -g gnosys copy

Features

Everything agents need to remember

A centralized brain with 50+ MCP tools. Sub-10ms reads, federated search, Web Knowledge Base, sandbox runtime, process tracing, and Dream Mode consolidation. No vector databases, no black boxes.

Centralized Brain

One ~/.gnosys/gnosys.db shared across all projects. 6-table schema with project_id and scope columns. Sub-10ms reads, automatic backups, one-command Obsidian export.

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 in one central DB. Project memory stays with code, user preferences follow you everywhere, global knowledge spans the org.

Memory Lensing

Filter by category, tags, status, author, confidence, dates. Compound lenses combine criteria with AND/OR logic.

Audit Log & Export

Every memory write is tracked in the audit log. Export to Obsidian-compatible markdown anytime with gnosys export. View full version history and non-destructively rollback any memory.

Obsidian Wikilinks

Cross-reference memories with [[wikilinks]]. Build a knowledge graph with backlinks, see connections, find orphaned links.

LLM Ingestion

Feed raw text and an LLM structures it into an atomic memory with title, tags, category, and relevance keywords.

Dream Mode

Idle-time consolidation: confidence decay, self-critique, summaries, and relationship discovery. Like biological sleep for your knowledge base.

Bulk Import

Import thousands of records from CSV, JSON, or JSONL. LLM-powered ingestion generates keyword clouds automatically. Batch commits, dedup, and resume support.

Multi-Project + Preferences

Central project registry, auto-detection from .git/package.json, project briefings, user preferences, and agent rules generation for Claude Code, Cursor, and more.

Web Knowledge Base

Turn any website into a /knowledge/ directory of searchable markdown. Pre-computed JSON index, zero-dependency runtime. Powers Sir Chats‑A‑Lot. Supports llms.txt for AI discoverability.

Sandbox Runtime

Persistent background process with Unix socket server. Agents import a tiny helper library and call memory operations like regular code. Near-zero context cost, no MCP overhead.

Process Tracing

Build call chains from source code with leads_to, follows_from, and requires relationships. Reflection API updates confidence based on real-world outcomes.

Portfolio Dashboard

Cross-project status dashboard with readiness scores, blocker tracking, and production-readiness assessment. gnosys status --web opens an interactive HTML dashboard.

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 PDFs, images (OCR), audio, video, and DOCX files as structured memories. Automatic text extraction feeds into the LLM structuring pipeline.

Multi-Machine Sync

Share your gnosys.db across machines via NAS or shared drive. Local cache for speed, remote source of truth for consistency. Built-in conflict detection with AI-mediated resolution.

How It Works

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

gnosys setup ides writes the gnosys-mcp wrapper with no args (not gnosys serve). Setup resolves the absolute path on your machine.

claude_desktop_config.json

{
  "mcpServers": {
    "gnosys": {
      "command": "gnosys-mcp",
      "args": []
    }
  }
}

One config covers all of Claude Desktop — Chat, Cowork, and Code. Set it up once. Since Cowork has no working directory of its own, it scopes memory by projectRoot.

.cursor/mcp.json

{
  "mcpServers": {
    "gnosys": {
      "command": "gnosys-mcp",
      "args": []
    }
  }
}

Setup writes both project .cursor/mcp.json and user-level ~/.cursor/mcp.json.

terminal

$ claude mcp add -s user gnosys -- gnosys-mcp

Also registers Claude Desktop when you run gnosys setup ides → Claude Code.

terminal

$ 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

{
  "mcpServers": {
    "gnosys": {
      "command": "gnosys-mcp",
      "args": []
    }
  }
}

~/.gemini/antigravity/mcp_config.json

{
  "mcpServers": {
    "gnosys": {
      "command": "gnosys-mcp",
      "args": []
    }
  }
}

~/.grok/config.toml

[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

{
  "mcp": {
    "gnosys": {
      "type": "local",
      "command": ["gnosys-mcp"]
    }
  }
}

2. Agent Rules — automatic with gnosys init

gnosys init detects your IDE and writes rules/hooks automatically. gnosys sync refreshes them with preferences and project conventions. Manual examples below if you prefer to edit by hand.

.cursor/rules/gnosys.mdc

---
description: Gnosys persistent memory
alwaysApply: true
---

# Gnosys Memory System

## Retrieve memories
- At task start, call gnosys_discover with keywords
- Load results with gnosys_read
- Trigger on: "recall", "remember when", "what did we decide"

## Write memories
- Trigger on: "remember", "memorize", "save this", "don't forget"
- Also write on decisions, preferences, specs, post-task findings

## Key Tools
gnosys_discover → find memories  gnosys_add → write
gnosys_read     → load content   gnosys_update → modify
gnosys_hybrid_search → best search
gnosys_ask → Q&A with citations
… plus 25 more tools (maintain, history, graph, etc.)

CLAUDE.md

# Gnosys Memory

This project uses Gnosys for persistent memory via MCP.

## Read first
- At task start, call gnosys_discover with keywords
- Load results with gnosys_read
- On "recall", "remember when", "what did we decide" → search first

## Write automatically
- On "remember", "memorize", "save this" → call gnosys_add
- Decisions/preferences → commit to decisions/
- Specs → commit BEFORE starting work
- After implementation → commit findings

## Key tools
| Action | Tool |
| Find   | gnosys_discover → gnosys_read |
| Search | gnosys_hybrid_search, gnosys_ask |
| Write  | gnosys_add, gnosys_add_structured |
| Update | gnosys_update, gnosys_reinforce |

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.

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.

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.

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

50+ tools + multi-project
routing over stdio

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 Read the Docs

Persistent memoryfor AI agents

Everything agents need to remember

Centralized Brain

Federated Search

Three-Scope Architecture

Memory Lensing

Audit Log & Export

Obsidian Wikilinks

LLM Ingestion

Dream Mode

Bulk Import

Multi-Project + Preferences

Web Knowledge Base

Sandbox Runtime

Process Tracing

Portfolio Dashboard

Guided Status Updates

Multimodal Ingestion

Multi-Machine Sync

Add to your editor in 2 minutes

1. MCP Server Config — manual fallback

2. Agent Rules — automatic with gnosys init

Install & setup (once per machine)

Initialize each project

Refresh rules (optional)

Your agent remembers

No black boxes

Give your agents a memory

Persistent memory
for AI agents