v1.1.3 · Latest MIT License on PyPI

v1.0.0 · Open Source · MIT

Local Cognitive
Infrastructure
for AI Agents

CogniRepo gives AI agents persistent semantic memory, a knowledge graph, AST indexing, BM25 retrieval, and 34 MCP tools — so they stop forgetting everything between sessions. No API required. Fully offline.

View on GitHub pip install cognirepo How it works ↓

terminal

# ~50 MB install — no PyTorch, no CUDA required
pip install cognirepo

# One-command setup: init + index + MCP config
cognirepo setup

# Start the MCP server — Claude, Cursor, VS Code, Gemini
cognirepo prime

# Or use uvx (no install needed)
uvx cognirepo prime

scroll

How it works

Context that persists across sessions

Every AI session starts cold. CogniRepo fixes that by building a cognitive layer between your codebase and your AI agents — memory that survives process restarts.

Index your codebase

AST parser (tree-sitter) extracts symbols, call graphs, and docstrings across Python, JS, TS, Go, Rust, Java. Stored in a FAISS vector index + NetworkX knowledge graph + BM25 full-text index. Atomic writes — crash-safe at any size.

cognirepo setup

AI agents query via MCP

The MCP server exposes 34 tools. Agents call get_agent_bootstrap() for a single-call session start (~300 tokens vs ~900 for 4 calls), then context_pack() for packed, token-efficient context.

get_agent_bootstrap() → resume in one call

Memory persists between sessions

Decisions, errors, episode logs, and user preferences survive session boundaries. Encrypted at rest with Fernet. Cross-process FAISS freshness — multiple agents share the same memory without stale snapshots.

get_last_context() → resume instantly

Features

Everything an AI agent needs to remember

Semantic Memory

FAISS-powered vector store with ONNX embeddings (~50 MB — no PyTorch, no CUDA). Similarity search across codebase symbols, docs, and episodic logs. Cross-process freshness via mtime checks.

FAISS · ONNX · 384-dim

Knowledge Graph

NetworkX DiGraph tracks IMPORTS / CALLS / INHERITS / CALLS_API / DEFINED_IN / QUERIED_WITH edges across repos. Multi-repo org graph with cross-service traversal. AI agents add DISCOVERED edges dynamically.

NetworkX · Multi-repo · Encrypted

AST Indexer

Tree-sitter parses Python, JS, TS, Go, Rust, Java. Extracts functions, classes, symbols, decorators, base classes, arrow functions, and call relationships. Atomic writes (tmp + os.replace + fsync) — never corrupts on crash.

tree-sitter · 6 languages · Crash-safe

MCP Server — 34 Tools

FastMCP stdio transport exposes 34 tools. Works with Claude Code, Cursor, VS Code Copilot, Gemini — any agent that speaks Model Context Protocol. get_agent_bootstrap() cuts session start from 4 calls to 1.

FastMCP · stdio · uvx compatible

Episodic Memory

Timestamped log of decisions, errors, and milestones — searchable by BM25 + time range. record_decision() writes architectural choices that survive forever. supersede_learning() replaces stale knowledge in one call.

BM25 · Time-range · Persistent

Hybrid Retrieval

Blends vector score (0.5) + graph score (0.3) + behaviour score (0.2). BM25 as episodic side-channel and embedding-failure fallback. Confidence gate — code hits must score ≥0.25 or retrieval returns a structured failure, never README noise.

3-signal blend · BM25 · Config-tunable

Security & Reliability

Fernet AES-128-CBC encryption at rest, secrets in OS keychain. Circuit breaker monitors RSS and degrades gracefully before OOM. Idle resource eviction frees ~400 MB after configurable TTL. OOM-safe at any repo size.

Fernet · Circuit-breaker · OOM-safe

Org-Wide Search

org_wide_search() spans all registered repos in one query. Cross-service call graph maps how microservices call each other. cognirepo org rewire repairs CALLS_API edges missed by indexing order.

Multi-repo · Service topology

Behaviour Tracking

Opt-in query recording across context_pack, lookup_symbol, who_calls, and more. Feedback scores propagate to vector store with temporal decay. Auto-summarizes interaction style every 10 queries.

Opt-in · Encrypted · Privacy-first

Architecture

Clean layers, no magic

Tools are the single entry point. All retrieval goes through hybrid.py. All storage lives under .cognirepo/. No surprises.

AI Agents (Claude · Cursor · VS Code · Gemini)

MCP Server
FastMCP · stdio · 34 tools

Semantic Memory
FAISS · ONNX

Knowledge Graph
NetworkX

AST Index
tree-sitter

BM25 Index
Episodic

Storage: .cognirepo/ · Fernet encrypted

Your Codebase

Hybrid retrieval score formula

final = 0.5 × vector_score + 0.3 × graph_score + 0.2 × behaviour_score

BM25 runs as episodic side-channel and embedding-failure fallback · weights config-overridable

MCP Tools

34 tools, one protocol

All tools accept repo_path — one server process can serve multiple repos without cross-repo data leaks.

Session

get_agent_bootstrap() get_session_brief() get_last_context() get_session_history()

Code Navigation

lookup_symbol() who_calls() context_pack() architecture_overview() subgraph() dependency_graph() semantic_search_code() explain_change() find_symbol_path() get_service_endpoints()

Memory

store_memory() retrieve_memory() log_episode() episodic_search() record_decision() supersede_learning() search_token()

Org Graph

org_wide_search() org_dependencies() cross_repo_traverse() cross_repo_search() link_repos() list_org_context()

Diagnostics

graph_stats() search_docs()

User Profile

get_user_profile() record_user_preference() record_error() get_error_patterns()

Ready to give your AI agents a memory?

One pip install. One cognirepo setup. Works with Claude Code, Cursor, VS Code, and Gemini out of the box. No API key. No cloud. Fully local.

Star on GitHub View Changelog →

Local Cognitive Infrastructure for AI Agents