Gnapsis
Code intelligence graph - MCP server for knowledge management with Neo4j
Ask AI about Gnapsis
Powered by Claude Β· Grounded in docs
I know everything about Gnapsis. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Gnapsis
Code intelligence graph - MCP server for semantic codebase understanding with PostgreSQL + Apache AGE.
What is Gnapsis?
Gnapsis is an MCP (Model Context Protocol) server that helps AI assistants understand codebases through a semantic knowledge graph. Instead of just searching text, it tracks entities (domains, features, modules, structs, functions), their relationships, and anchors them to specific code locations.
Think of it as a structured memory layer for AI coding assistants.
Features
- Semantic Knowledge Graph: Organize entities in a hierarchy (Domain β Feature β Namespace β Component β Unit)
- Document References: Anchor entities to code with line-level precision
- Semantic Search: Find entities by meaning, not just keywords
- Subgraph Queries: Extract relevant context within token budgets
- Staleness Detection: Know when references become outdated via git
- TOON Output: Token-efficient output format (40-60% fewer tokens than JSON)
- Multi-Project Support: Each project gets its own graph in a shared database
Quick Start
1. Prerequisites
PostgreSQL with Apache AGE and pgvector:
# Using Docker Compose (recommended)
# Builds a custom image with AGE 1.6.0 (PG17) + pgvector 0.8.0
docker compose up -d
This starts a PostgreSQL instance with Apache AGE and pgvector extensions pre-configured, including the initial graph creation.
Rust 1.75+ for building from source.
2. Installation
git clone https://github.com/e7nd7r/gnapsis.git
cd gnapsis
# Install the binary
cargo install --path .
3. Configuration
Gnapsis uses a layered configuration approach (highest priority last):
- Global config (
~/.config/gnapsis/config.toml) - database and embedding settings - Project config (
.gnapsis.tomlin your project root) - project name and sources - Environment variables (
GNAPSIS_*) - overrides for any setting
Global config (~/.config/gnapsis/config.toml):
[postgres]
uri = "postgresql://postgres:postgres@localhost:5432/gnapsis_dev"
[embedding]
provider = "fastembed"
model = "BAAI/bge-small-en-v1.5"
dimensions = 384
Project config (.gnapsis.toml in your project root):
[project]
name = "my-project"
# Graph name is always gnapsis_<name> (e.g., gnapsis_my_project)
Multi-source projects - span multiple directories (e.g., code + docs):
[project]
name = "my-project"
[[project.sources]]
id = "default"
path = "/path/to/code-repo"
[[project.sources]]
id = "docs"
path = "/path/to/documentation-vault"
See .gnapsis.toml.example for a complete reference.
4. MCP Setup
Add to your project's .mcp.json:
{
"mcpServers": {
"gnapsis": {
"command": "gnapsis",
"args": ["mcp"]
}
}
}
5. Initialize the Project
Once connected via MCP, initialize the database:
Use init_project to set up the database schema
This creates the schema, scopes, and default categories.
Workflow
Understanding the Hierarchy
Gnapsis organizes knowledge in scopes (levels of abstraction):
Domain (e.g., "Authentication", "Payments")
βββ Feature (e.g., "JWT Validation", "OAuth Flow")
βββ Namespace (e.g., "auth::providers", "services")
βββ Component (e.g., UserService struct, AuthTrait)
βββ Unit (e.g., validate() method, MAX_RETRIES constant)
Each entity has a category that classifies it within its scope:
- Domain:
core,infrastructure - Feature:
functional,technical,non-functional - Namespace:
module,library - Component:
struct,trait,enum,class - Unit:
function,method,constant,field
Creating Entities
Entities need: name, description, category, and at least one reference to code.
Example - creating a domain:
Use create_entity with:
- name: "Authentication"
- description: "Domain for user authentication and authorization"
- category_ids: [<core-domain-category-id>]
- commands: [{ type: "add", ref_type: "text", document_path: "README.md", description: "Auth section", start_line: 10, end_line: 20 }]
Example - creating a component under a namespace:
Use create_entity with:
- name: "UserService"
- description: "Service for user management operations"
- category_ids: [<struct-category-id>]
- parent_ids: [<services-namespace-id>]
- commands: [{ type: "add", ref_type: "code", document_path: "src/services/user.rs", lsp_symbol: "UserService", description: "UserService struct" }]
Querying the Graph
Get project overview - See all domains, features, namespaces, and categories:
Use project_overview
Semantic search - Find entities by meaning:
Use search with query: "user authentication validation"
Subgraph query - Get related entities within a token budget:
Use query with semantic_query: "how does authentication work"
Find entities - Filter by scope, category, or parent:
Use find_entities with scope: "Component", category: "struct"
Analyzing Documents
Check what's tracked in a file and detect stale references:
Use analyze_document with document_path: "src/services/user.rs"
Validating the Graph
Check for integrity issues (orphans, cycles, missing references):
Use validate_graph
Output Formats
Tools that return large results support TOON (Token-Oriented Object Notation) for 40-60% token savings:
Use query with semantic_query: "...", output_format: "toon"
Supported on: query, search, analyze_document, project_overview
Tools Reference
| Tool | Description |
|---|---|
init_project | Initialize database schema |
project_overview | Get taxonomy, entities, and stats |
create_category | Create new category at a scope |
create_entity | Create entity with references |
update_entity | Update entity (re-embeds on description change) |
delete_entity | Delete entity (must have no children) |
get_entity | Get entity with full context |
find_entities | Find entities by scope/category/parent |
search | Semantic search across entities and references |
query | Semantic subgraph extraction |
get_document_entities | Get entities referenced in a document |
analyze_document | Document analysis with staleness detection |
alter_references | Bulk update/delete references |
validate_graph | Check graph integrity |
lsp_refresh | Refresh references using LSP data |
get_changed_files | Get files changed between commits |
Development
Gnapsis uses just for development tasks:
just db-up # Start the database
just build # Build the project
just test # Run unit tests
just test-integration # Run integration tests (requires db-up)
just lint # Run clippy
just fmt # Format code
just db-shell # Connect to psql
just cypher "MATCH (n) RETURN n" # Run a Cypher query
Run just with no arguments to see all available commands.
License
MIT - See LICENSE for details.
