# Knownbase MCP Server

[![smithery badge](https://smithery.ai/badge/zeeshan-zstech/knownbase)](https://smithery.ai/servers/zeeshan-zstech/knownbase)

**Persistent, searchable project memory for AI agents, over the Model Context Protocol.**

[Knownbase](https://knownbase.dev) is a hosted MCP server that gives AI coding agents (Claude,
Cursor, ChatGPT, Claude Code, Windsurf, and any other MCP-compatible client) a place to read and
write durable notes, decisions, and handoffs that live *outside* your git history: the working
memory an agent otherwise loses the moment a session ends.

This repository documents the `/mcp` endpoint: how to connect, what tools it exposes, and how
authentication works. There is no local install: Knownbase is a remote, streamable-HTTP MCP
server, so connecting is just pointing your client at a URL.

```
https://knownbase.dev/mcp
```

## The problem this solves

AI agents are stateless between sessions. Every new chat, every new terminal, every restarted
IDE window starts from zero. The agent re-reads your code but has no memory of *why* things are
the way they are:

- Architecture decisions and the tradeoffs behind them
- Debugging trails ("we tried X, it didn't work because Y")
- Conventions and gotchas that aren't obvious from the code itself
- Task handoffs between sessions, or between you and a teammate's agent
- Anything you don't want cluttering git history but still need the agent to know

Without a memory layer, you end up re-explaining the same context every session, or the agent
re-discovers (and re-breaks) the same thing twice. Knownbase gives the agent a workspace it can
search and write to directly, so that memory persists and compounds instead of resetting.

## Quick start

1. Create a free workspace at [knownbase.dev](https://knownbase.dev) (no card required).
2. Connect your MCP client to `https://knownbase.dev/mcp`; see
   [docs/CONNECTING_CLIENTS.md](docs/CONNECTING_CLIENTS.md) for exact steps per client
   (Claude, Claude Code, ChatGPT, Cursor, and generic MCP clients).
3. Authenticate with either a static API key or OAuth 2.1 (most clients auto-discover OAuth);
   see [docs/AUTHENTICATION.md](docs/AUTHENTICATION.md).
4. Start a task with `get_context` to load what's already known, write durable knowledge with
   `remember`, and fall back to `search_notes` / `get_note` / `upsert_note` for direct control.
   Full tool reference: [docs/TOOLS.md](docs/TOOLS.md).

## What it exposes

| Tool | Purpose |
| --- | --- |
| `list_projects` | List project categories and note counts in the workspace |
| `get_context` | One-call project orientation: constraints, decisions, status, open items, and recent changes, ranked and packed to a token budget |
| `search_notes` | Search by text, project, tag, status, or last-modified date (keyword or semantic) |
| `get_note` | Read one note in full, with its links/backlinks |
| `get_notes` | Batch-read up to 50 notes in one call |
| `remember` | Store a durable fact/decision/constraint in one call: derives the title, checks for duplicates or contradictions, reports what it did |
| `checkpoint` | Close a work session as structured durable state: summary, decisions, discoveries, open items, next actions |
| `get_changes_since` | Resume from another agent, session, or machine via an opaque cursor, without reloading the project |
| `upsert_note` | Create a note, or partially update an existing one |
| `patch_note` | Change part of a body (append, prepend, or literal find-and-replace) without resending it |
| `delete_note` | Soft-delete (trash) a note |
| `list_note_revisions` | List a note's saved prior versions |
| `get_note_revision` | Read the full body of one historical revision |
| `workspace_info` / `usage_summary` | Plan, limits, usage, and this key's own access scope |
| `rename_project` | Bulk-rename a project across every note |
| `rename_tag` | Bulk-rename or remove a tag across every note |
| `backup_project` | Export full content of one project inline, for backup/portability |

Notes also carry optional typed, temporal metadata (`decision` / `fact` / `constraint` / …, plus
a `current` / `superseded` / `disputed` lifecycle) that `get_context` ranks and filters on. See
[Typed, temporal memory](docs/TOOLS.md#typed-temporal-memory) in the tool reference.

Full parameter-level reference, including the lean-by-default response shapes designed to save
agent tokens, is in [docs/TOOLS.md](docs/TOOLS.md).

## Why a remote, hosted MCP server

Every note is scoped to your own workspace; nothing is shared across tenants. Full-text search
(and, on supported plans, semantic/meaning-based search) runs server-side, so agents get results
without loading your entire notes corpus into context. Notes are versioned (every edit snapshots
a revision) and soft-deleted (trash, not permanently gone), so an agent's write is never a
one-way door.

## Links

- [Homepage](https://knownbase.dev/): what Knownbase is and who it's for
- [Features](https://knownbase.dev/features)
- [Pricing](https://knownbase.dev/pricing): free tier (3 projects, 300 notes, 2 MCP keys), plus
  Go / Solo / Team / Business plans, each with a 7-day free trial
- [Blog](https://knownbase.dev/blog): guides on MCP, agent memory, and handoffs
- [llms.txt](https://knownbase.dev/llms.txt): machine-readable product/endpoint summary
- [Contact](https://knownbase.dev/contact) · hello@knownbase.dev

## Repository contents

- [`docs/AUTHENTICATION.md`](docs/AUTHENTICATION.md): API keys, OAuth 2.1 flow, project-scoped keys
- [`docs/CONNECTING_CLIENTS.md`](docs/CONNECTING_CLIENTS.md): per-client setup (Claude, Claude Code, ChatGPT, Cursor, others)
- [`docs/TOOLS.md`](docs/TOOLS.md): full tool reference with input/output shapes
- [`server.json`](server.json): [MCP Registry](https://registry.modelcontextprotocol.io) manifest

This repository documents a hosted service; it does not contain the Knownbase server's source
code. Found an issue with these docs, or a mismatch with actual server behavior? Please
[open an issue](https://github.com/zeeshandev6/knownbase-mcp/issues) or email
hello@knownbase.dev.

## License

Documentation in this repository is [MIT licensed](LICENSE). Use of the Knownbase service itself
is governed by its [Terms of Service](https://knownbase.dev/terms).