🧠 kognit

Give your AI agent a senior developer's memory

Every AI coding session starts with amnesia. kognit fixes that.

• 🔍 Analyzes your codebase in 30 seconds using recursive, semantic syntax structures.
• 🕸️ Maps every dependency relationship and resolves local import maps to compute blast-radius.
• 🤖 Serves architectural memory directly to Claude Code, Cursor, and Windsurf via MCP.

The Problem

You open a new Claude Code or Cursor session. The AI has absolutely no idea:

• Why authorization is handled in middleware/auth.py instead of the route controllers.
• That changing the User email column schema breaks 4 other files.
• What specific coding conventions, styles, and naming rules your team requires.
• How your local Redis caching TTL and eviction paths are structured.

You spend 20 minutes re-explaining context and copying code snippets. Every. Single. Session.

The Solution

By mapping codebase imports into a local JSON graph, kognit exposes direct tools for AI clients to query downstream dependencies and conventions.

How It Works

kognit runs a 4-stage local pipeline on your machine:

1. Scans your codebase and identifies architecturally significant files across any language stack
2. Extracts every import statement to build a precise dependency graph — who imports who, what depends on what
3. Analyzes the compressed graph using your AI provider to generate semantic architectural understanding
4. Serves this memory via a local MCP server — your AI agent queries it automatically during coding sessions

No cloud. No database. No background sync.
Think of it like git status — stateless, on-demand, always accurate.

Quick Start

Get your AI agent up and running with permanent repository context in under 90 seconds.

# 1. Analyze your project
npx kognit-cli analyze

# 2. Start the local MCP server
npx kognit-cli serve

Your AI agent now has permanent, structural memory of your project.

Usage: Hooking up your AI

Depending on which AI tool you use, there are two ways to consume kognit.

1. For Claude Desktop, Cursor, and Windsurf (MCP Flow)

These modern tools support the Model Context Protocol (MCP), meaning they can call kognit-cli serve dynamically.

Claude Desktop: Add this to your claude_desktop_config.json (located in %APPDATA%\Claude on Windows or ~/Library/Application Support/Claude on Mac):

{
  "mcpServers": {
    "kognit": {
      "command": "npx",
      "args": ["kognit-cli", "serve"]
    }
  }
}

Restart Claude, and it will now automatically use the tools whenever you ask questions about your architecture!

Cursor: Go to Cursor Settings > Features > MCP, add a new MCP server:

• Name: kognit
• Command: npx kognit-cli serve

2. For GitHub Copilot, ChatGPT, and others (Manual Flow)

If your AI tool doesn't support MCP yet, you use the MEMORY.md file that was generated during the analysis step. It acts as a universal fallback!

• GitHub Copilot / IDE Chat: Just type: @workspace based on the rules in MEMORY.md, how do I...
• ChatGPT / DeepSeek / Claude.ai: Open MEMORY.md, copy the contents (~3KB of text), and paste it into your very first prompt to give the web AI perfect architectural context.

Managing Memory

Codebases change. kognit makes it easy to keep your AI's memory fresh:

# Check how old your memory is and see project stats
npx kognit-cli status

# Force a re-analysis (kognit skips analysis if memory is < 1 hour old to save API costs)
npx kognit-cli analyze --force

Customizing Scans (.kognitignore)

To exclude specific directories or files from being scanned (e.g. documentation, legacy scripts, or database migrations), create a .kognitignore file in your project root:

# .kognitignore
docs/
scripts/legacy/
migrations/

This keeps your character budget spent strictly on high-value source files!

What kognit Generates

1. MEMORY.md (Human-Readable Architectural Blueprint)

Here is the real output generated by running kognit directly on our sample FastAPI SaaS demo codebase:

# 🧠 Project Memory
> Auto-generated by [kognit](https://github.com/junaid4231/kognit) 
> Stack: Python • FastAPI • SQLAlchemy

> ⚠️ **CRITICAL INSTRUCTION FOR AI AGENTS:**
> This document maps **macro-level file dependencies**. It is highly effective for structural refactoring.
> **LIMITATION:** If the user asks you to modify a specific Symbol, Class, Database Model, or Function inside a heavily imported file, **DO NOT** rely solely on the dependency graph below. You MUST use your native codebase search/grep tools to find exact references to that symbol across the codebase (including frontend, migrations, and schemas).

## 📌 Project Overview
The project is a SaaS core API built with FastAPI, providing features such as user registration, payment processing, and dashboard summaries. Key endpoints include /register, /checkout, and /dashboard. The project also integrates with Stripe for payment processing and uses Redis for caching.

## 🏗️ Architecture Style
Layered Architecture — routes/* call services/* which call db/client.py; no route imports db directly. For example, routes/payments.py calls services/payment_service.py which calls db/client.py.

## 📁 Folder Roles
| Folder | Purpose |
|--------|---------|
| `routes` | Handles HTTP requests and responses, with files like payments.py and users.py defining API endpoints. |
| `services` | Encapsulates business logic, with files like payment_service.py and user_service.py providing functions for payment processing and user management. |

## 🕸️ Dependency Map

**Most Critical Files** (highest blast radius — change carefully):
| File | Imported By |
|------|------------|
| `db/client` | 3 files depend on this |
| `middleware/auth` | 3 files depend on this |
| `models/user` | 3 files depend on this |
| `db/redis_client` | 1 files depend on this |
| `routes` | 1 files depend on this |

**Entry Points:**
- `app`

**Orphaned Files** (nothing imports these — safe to delete or review):
None detected

## ⚙️ Key Conventions
1. All DB sessions are injected via get_db() FastAPI dependency — never instantiate Session directly in route handlers; session lifecycle is managed by context manager in db/client.py using try/finally commit/rollback pattern.

2. Use require_auth() dependency to verify JWT headers in protected routes like /dashboard.


## ⚠️ What To Know Before Coding
**1. All DB sessions are injected via get_db() FastAPI dependency**
never instantiate Session directly in route handlers; session lifecycle is managed by context manager in db/client.py using try/finally commit/rollback pattern.

**2. Important Rule / Gotcha**
Use require_auth() dependency to verify JWT headers in protected routes like /dashboard.

**3. Important Rule / Gotcha**
Use get_redis_client() to interact with the Redis cache.

## 💡 Suggested Improvements
- Implement retry logic for database queries to handle transient errors.
- Add more robust error handling for Stripe webhooks to handle unexpected payload formats.

---
*Generated by kognit — give your AI agent a senior developer's memory*  
*Run `npx kognit-cli analyze` to refresh after significant code changes.*
---

2. Terminal Card Output

Upon scanning, kognit outputs a clean, high-fidelity metrics summary:

╔════════════════════════════════════════╗
║           kognit analysis complete      ║
╚════════════════════════════════════════╝

📦 Project:    fake-saas-project
🔧 Stack:      Python / FastAPI / SQLAlchemy
🏗️  Arch:      Layered Architecture — routes/* call services/* which call db/client.py; no route imports db directly. For example, routes/payments.py calls services/payment_service.py which calls db/client.py.

📊 Analysis
   Files scanned:        10
   Relationships mapped: 13
   Topics identified:    7
   Critical files:       db/client (3 dependents)

📁 Output
   ✅ MEMORY.md    3.16 KB  (paste into any AI chat)
   ✅ memory.json  8.31 KB  (used by MCP server)

🚀 Next step:
   npx kognit-cli serve
   (starts local MCP server for Claude Code / Cursor)

How It Compares

| Feature | repomix | AGENTS.md | kognit-cli | | :--- | :---: | :---: | :---: | | Setup Time | 2 min | 30 min | 90 sec | | Dependency Graph | ❌ | ❌ | ✅ | | Queryable via MCP | ❌ | ❌ | ✅ | | Understands Why | ❌ | manual | ✅ |

AI Provider Options

By default, kognit uses Groq (free, fast, default) to analyze the codebase, but can be configured to use any other primary LLM provider.

npx kognit-cli analyze                                     # Groq (Llama-3.3-70b-versatile, default)
npx kognit-cli analyze --provider claude                   # Anthropic Claude (claude-sonnet-4-20250514)
npx kognit-cli analyze --provider gemini                   # Google Gemini (gemini-2.0-flash)
npx kognit-cli analyze --provider ollama                   # Local Ollama (no internet/API key needed)

MCP Tools Reference

When running npx kognit-cli serve, your AI agent (Claude Code, Cursor, Windsurf, etc.) gets immediate, programmatic access to these 5 tools:

• get_architecture(): Provides a high-level project stack summary, directories, roles, and architecture style guidelines.
• get_dependencies(file_path): Identifies direct and recursive import paths required by a specific file.
• get_dependents(file_path, include_tests=true): Visualizes the blast-radius of changing a file by returning all other files that import it.
• get_conventions(category_keyword): Fetches styling rules and architecture guidelines matched by category.
• search_memory(query): Performs instant zero-network keyword-scoring semantic searches over codebase topics (e.g. "how is stripe billing configured?").

Contributing & Development

We believe that AI coding agents deserve the exact same high-fidelity architectural knowledge that a human senior developer uses. Contributions, bug reports, and features are highly welcome!

Development Setup

# Clone the repository
git clone https://github.com/junaid4231/kognit.git
cd kognit

# Install dependencies
npm install

# Run the test suite (automated quality gates)
node test.js

License

This project is licensed under the terms of the MIT License.

Built with 🧠 by Muhammad Junaid (@junaid4231).