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.
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-apiMon 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.
A developer states a decision in chat. Nothing is saved yet.
The agent calls gnosys_discover to check for a duplicate. Nothing matches.
gnosys_add_structured saves the decision. The agent writes the title, category, tags and keywords itself.
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 sessionThu 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-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-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>
Same morning, a different agent. Codex reads the same local Gnosys database.
Codex recalls the tenant isolation decision before it writes any code.
The decision shapes new code in another tool. Nobody had to repeat it.
Install Gnosys and run setup to connect it to your agents.
0:00 / 0:54
The project, people, IDs and times are examples. Tool names, arguments and result formats match Gnosys OSS.
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.
Store
The memory lives in ~/.gnosys/gnosys.db, scoped to the project. Closing the chat does not lose it.
Recall
gnosys_recall ranks matches by keyword with no LLM call. gnosys_read loads one by ID.
Share
Every MCP client on the machine reads the same database. Claude Code, Cursor and Codex see the same memory.
Features
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.
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
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.
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.
2. Agent Rules — generated from your installed version
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.
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.