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.

Fast path: run gnosys setup ides once to wire MCP for Claude, Cursor, Codex, Grok Build, Gemini CLI, Antigravity, and Claude Desktop.

IDE MCP wiring is user-level — run gnosys setup ides once per machine. Project registration in gnosys init is per-directory — run it in each codebase you want memory-enabled. 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.

Setup wizards (v5.4.2+): gnosys setup runs the full interactive flow. To configure just one piece: gnosys setup models, gnosys setup ides, gnosys setup remote, gnosys setup dream.

1. MCP Server Config — or edit manually

claude_desktop_config.json

{
  "mcpServers": {
    "gnosys": {
      "command": "gnosys",
      "args": ["serve"]
    }
  }
}

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",
      "args": ["serve"]
    }
  }
}

terminal

$ claude mcp add gnosys gnosys serve

~/.codex/config.toml

[mcp.gnosys]
type = "local"
command = ["gnosys", "serve"]

~/.gemini/settings.json

{
  "mcpServers": {
    "gnosys": {
      "command": "gnosys",
      "args": ["serve"]
    }
  }
}

~/.gemini/antigravity/mcp_config.json

{
  "mcpServers": {
    "gnosys": {
      "command": "gnosys",
      "args": ["serve"]
    }
  }
}

~/.grok/config.toml

[mcp.gnosys]
command = "gnosys"
args = ["serve"]
startup_timeout_sec = 90

startup_timeout_sec = 90 gives gnosys room to spin up on a cold start. If grok mcp doctor still reports a timeout, that's Grok's own probe limit — not gnosys.

opencode.json

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

2. Agent Rule — teach your AI when to use Gnosys

.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

npm install -g gnosys then gnosys setup to configure your LLM provider and connect to your IDE. Works with Claude Code, Claude Desktop (Chat / Cowork / Code), Cursor, Codex, Gemini CLI, Antigravity, Grok Build, OpenCode, or any MCP client.

Initialize your project

gnosys init registers the project in the central brain and creates .gnosys/gnosys.json for project identity.

Generate agent rules

gnosys sync --target all writes tool instructions into your IDE's rules file (CLAUDE.md, .cursorrules, etc.). Use --global for machine-wide rules.

Your agent remembers

Decisions, architecture choices, conventions, requirements — all persisted as atomic markdown files your agent can discover and reference 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 — or edit manually

2. Agent Rule — teach your AI when to use Gnosys

Install & setup

Initialize your project

Generate agent rules

Your agent remembers

No black boxes

Give your agents a memory

Persistent memory
for AI agents