Open Source · MIT License

Persistent memory
for AI agents

Gnosys gives AI agents persistent, portable, shared memory across sessions and projects. It starts with 19 core MCP tools and can expand in-session to all 56, with 9 LLM providers, federated search, multimodal ingestion, a serverless Web Knowledge Base, process tracing, and Dream Mode consolidation.

macOS Linux Windows
$ npm install -g gnosys copy

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

You

Remember: we decided to use Postgres row-level security for tenant isolation, not app-level filters.

Agent

I'll check Gnosys for an existing memory first.

Called gnosys_discover

Called gnosys_add_structured

Agent

Saved to Gnosys as deci-01KZ7Q3M8T4VXN2R6HJCW5PB9E under decisions. Future sessions in this project can recall it.

Gnosys MCP tool calls

gnosys_discoverdone

{
  "query": "tenant isolation postgres row-level security",
  "projectRoot": "/Users/sam/code/acme-api"
}
No memories found for "tenant isolation postgres row-level security". Try different keywords.

gnosys_add_structureddone

{
  "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"
}
Memory added to [project]: **Tenant isolation uses Postgres row-level security**
ID: deci-01KZ7Q3M8T4VXN2R6HJCW5PB9E
  1. A developer states a decision in chat. Nothing is saved yet.
  2. The agent calls gnosys_discover to check for a duplicate. Nothing matches.
  3. gnosys_add_structured saves the decision. The agent writes the title, category, tags and keywords itself.
  4. 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

You

What did we decide for tenant isolation?

Called gnosys_recall

Called gnosys_read

Agent

You 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_recalldone

{
  "query": "tenant isolation decision",
  "projectRoot": "/Users/sam/code/acme-api"
}
<gnosys-recall>
[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-recall>

gnosys_readdone

{
  "path": "deci-01KZ7Q3M8T4VXN2R6HJCW5PB9E",
  "projectRoot": "/Users/sam/code/acme-api"
}
[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.
  1. Three days later, a new session starts with no chat history.
  2. gnosys_recall searches the project's memories by keyword and ranks them.
  3. gnosys_read loads the top hit by ID, with who declared it and when.
  4. 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

You

Add an invoices table for the billing service.

Called gnosys_recall

Agent

Created migrations/0042_invoices.sql with row-level security on the new table, per deci-01KZ7Q3M8T4VXN2R6HJCW5PB9E.

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_recalldone

{
  "query": "invoices table tenant database",
  "projectRoot": "/Users/sam/code/acme-api"
}
<gnosys-recall>
[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.
</gnosys-recall>
  1. Same morning, a different agent. Codex reads the same local Gnosys database.
  2. Codex recalls the tenant isolation decision before it writes any code.
  3. The decision shapes new code in another tool. Nobody had to repeat it.

Give your agents a memory

npm install -g gnosys
gnosys setup
  1. Install Gnosys and run setup to connect it to your agents.

The project, people, IDs and times are examples. Tool names, arguments and result formats match Gnosys OSS.

  1. 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.

  2. Store

    The memory lives in ~/.gnosys/gnosys.db, scoped to the project. Closing the chat does not lose it.

  3. Recall

    gnosys_recall ranks matches by keyword with no LLM call. gnosys_read loads one by ID.

  4. Share

    Every MCP client on the machine reads the same database. Claude Code, Cursor and Codex see the same memory.

Everything agents need to remember

A local-first SQLite brain with 19 core MCP tools by default and 56 available 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.

Claims verified against the open-source v6.2.1 codebase on July 20, 2026. Feature prerequisites and limitations are documented in the user guide.

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.

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

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 Integration Guide

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.

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

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
{
  "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"]
    }
  }
}

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.

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
19 core / 56 full tools
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.