Secrin - The living wiki that writes itself

The living wiki that writes itself.
Point Secrin at any codebase. It builds a knowledge graph, summarizes every function and class,
extracts your business domains, generates a Markdown wiki and keeps it all in sync on every commit.

Website · GitHub

What is Secrin?

Most wikis go stale the moment they're written. Secrin doesn't because it never needed a human to write it in the first place.

Secrin parses your codebase into a Neo4j knowledge graph, uses your LLM to generate plain-English summaries for every function, class, and file, identifies your business domains, and writes a structured Markdown wiki. A git hook keeps everything in sync automatically after every commit.

secrin init # interactive setup → .secrin.yml
secrin graph build --repo .# parse repo → Neo4j graph
secrin analyze # LLM summaries + vector embeddings
secrin domains # extract business domain concepts
secrin generate # write docs/wiki/
secrin chat "how does auth work?"# Q&A grounded in the graph

New engineer on the team? Run secrin chat "where should I add the billing endpoint?" and get a direct, sourced answer, no archaeology required.

Features

Feature	Description
Code knowledge graph	Neo4j graph of Files, Modules, Functions, Classes with CALLS, IMPORTS, and INHERITS edges
LLM summaries	Plain-English description of every node via Ollama, OpenAI, or Anthropic
Vector search	Semantic KNN search over embeddings stored directly in Neo4j vector indexes
Hybrid search	Combines vector KNN with 1-hop Cypher graph traversal for better recall
Domain extraction	Identifies business concepts (auth, payments, …) and links them to code nodes
Wiki generation	Markdown wiki with per-module pages, domain pages, and Mermaid architecture diagrams
Chat Q&A	Ask architecture questions; answers grounded in graph context, not hallucinated
Git hook	Post-commit hook auto-updates graph and wiki after every commit
Multi-LLM	Ollama (local) · OpenAI · Anthropic — switchable per repo via `.secrin.yml`
Dashboard	`secrin status` shows graph stats, coverage %, last analysis, wiki state

Installation

Requirements: Python ≥ 3.11, Poetry, Neo4j 5+

git clone https://github.com/secrinlabs/secrin
cd secrin
poetry install
# Start Neo4j (Docker — included in docker-compose.yml)
docker compose up neo4j -d
# Verify infrastructure
poetry run python scripts/verify.py

Local LLM (Ollama)

# Install Ollama → https://ollama.com
ollama pull qwen2.5-coder:0.5b # completion model
ollama pull mxbai-embed-large # embedding model (768d)

Cloud LLM

Set keys in .env before running secrin init:

OPENAI_API_KEY=sk-...
# or
ANTHROPIC_API_KEY=sk-ant-...

Quick Start

1 — Initialize

cd your-project
secrin init

The interactive wizard asks for your LLM provider, Neo4j connection, and wiki output directory, then writes .secrin.yml. Commit this file so teammates share the same defaults.

? LLM provider (ollama / openai / anthropic): ollama
? Ollama host [http://localhost:11434]:
? Ollama model [qwen2.5-coder:0.5b]:
? Embed model [mxbai-embed-large]:
? Neo4j URI [bolt://localhost:7687]:
? Neo4j username [neo4j]:
? Neo4j password:
? Neo4j database [neo4j]:
? Wiki output directory [docs/wiki]:
✓ Created .secrin.yml
✓ Updated .env (NEO4J_PASS)
✓ Connected to Neo4j (0 nodes found)
✓ Connected to Ollama (qwen2.5-coder:0.5b available)
Run `secrin graph build --repo <url-or-path>` to index your repo.

2 — Build the graph

# Current directory
secrin graph build --repo .# GitHub URL (cloned automatically)
secrin graph build --repo https://github.com/your-org/your-repo

3 — Generate summaries and embeddings

secrin analyze

Runs in two phases:

⠋ [Phase 1] Summarizing ollama / qwen2.5-coder:0.5b Function 48 Class 12 File 21
⠋ [Phase 2] Embedding mxbai-embed-large Function 48 Class 12 File 21
╭─ Analysis Results ────────────────────────╮
│ Label Summarized Embedded │
│ Function 612 612 │
│ Class 111 111 │
│ File 124 124 │
╰────────────────────────────────────────────╯
✓ Total nodes with summary: 847

4 — Generate the wiki

# Optional: identify business domain concepts
secrin domains
# Generate Markdown wiki
secrin generate

Output at docs/wiki/:

docs/wiki/
├── README.md ← auto-linked index
├── architecture.md ← system overview + Mermaid import graph
├── modules/
│ ├── packages-cli.md
│ └── packages-config.md
└── domains/
├── authentication.md
└── payment-processing.md

5 — Search and chat

# Semantic search
secrin search "rate limiting"
secrin search "JWT token validation" --verbose
# Architecture Q&A — grounded in the graph, not hallucinated
secrin chat "how does authentication work?"
secrin chat "where is the payment webhook handler?"
secrin chat "what calls the user repository?"

6 — Check status

secrin status

Secrin v2 your-project
──────────────────────────────────────────────────────────────
Graph 847 nodes · 2,341 edges
Files 124 · Functions 612 · Classes 111 · Modules 4
Domains 8 domain entities identified
Coverage 98% summarized · 96% embedded
Last analyzed 2 hours ago (main @ a3f9c12)
Neo4j ● connected bolt://localhost:7687
Wiki docs/wiki/ · 47 pages
.secrin.yml ✓ ollama / qwen2.5-coder:0.5b
──────────────────────────────────────────────────────────────

Configuration

`.secrin.yml` — team config (commit this)

llm:
provider: ollama # ollama | openai | anthropicmodel: qwen2.5-coder:0.5bembed_model: mxbai-embed-largebase_url: http://localhost:11434 # Ollama only; omitted for cloud providersneo4j:
uri: bolt://localhost:7687 # or AuraDB URI for a shared team graphusername: neo4jdatabase: neo4jwiki:
output_dir: docs/wikilanguages:
- python

`.env` — secrets (never commit)

NEO4J_PASS=your_password
# Cloud LLM providers (set whichever you use)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
# Optional overrides (if you don't use .secrin.yml)
LLM_PROVIDER=ollama
LLM_MODEL_OLLAMA=qwen2.5-coder:0.5b
OLLAMA_EMBEDDING_MODEL=mxbai-embed-large
EMBEDDING_DIMENSION=768

Provider comparison

Provider	Completions	Embeddings	Best for
Ollama	local model	local model	Offline / no API cost
OpenAI	GPT-4o-mini	text-embedding-3-small	Best quality + speed
Anthropic	Claude Haiku	Ollama fallback*	Best reasoning quality

* Anthropic has no embeddings API. When provider: anthropic, embed calls route to Ollama automatically.

Commands

Setup & monitoring

Command	Description
`secrin init`	Interactive wizard — creates `.secrin.yml`
`secrin init --force`	Reconfigure existing setup
`secrin status`	Dashboard: node counts, coverage, wiki state

Graph pipeline

Command	Description
`secrin graph build --repo <url\|path>`	Parse repo and build Neo4j graph
`secrin graph visualize`	Open Neo4j Browser (or AuraDB console)
`secrin analyze`	LLM summaries + vector embeddings
`secrin analyze --skip-embed`	Summaries only (no embeddings)
`secrin analyze --batch-size 25`	Smaller batches for slow machines
`secrin domains`	Extract business domain entities
`secrin domains --sample 500`	Sample more nodes for better coverage

Wiki

Command	Description
`secrin generate`	Write `docs/wiki/` from Neo4j
`secrin generate --skip-llm`	Fast mode — no narrative summaries
`secrin generate --output path/to/dir`	Custom output directory
`secrin diff`	Dry run: show what would change

Search & chat

Command	Description
`secrin search "<query>"`	Hybrid vector + graph search
`secrin search "<query>" --verbose`	Full summaries in results
`secrin search "<query>" --top 10`	Return top 10 results
`secrin chat "<question>"`	Architecture Q&A from the graph
`secrin chat "<question>" --top 12`	More context nodes

Automation

Command	Description
`secrin install-hooks`	Install git post-commit hook
`secrin post-commit`	Incremental graph + wiki update (called by hook)
`secrin post-commit --skip-wiki`	Update graph only

Architecture

secrin/
├── packages/
│ ├── cli/ # Main CLI package
│ │ ├── agents/
│ │ │ ├── llm_client.py # Unified Ollama / OpenAI / Anthropic client
│ │ │ ├── summarizer.py # Node summarization agent
│ │ │ ├── embedder.py # Vector embedding agent
│ │ │ ├── domain_extractor.py # Business domain extraction
│ │ │ └── wiki_writer.py # Markdown wiki generator
│ │ ├── commands/
│ │ │ ├── init.py # Interactive setup wizard
│ │ │ ├── status.py # Live dashboard
│ │ │ ├── chat.py # Architecture Q&A
│ │ │ ├── diff.py # Wiki dry-run diff
│ │ │ ├── graph.py # graph build + visualize
│ │ │ ├── analyze.py # summarize + embed (Rich progress)
│ │ │ ├── search.py # hybrid search
│ │ │ ├── domains.py # domain extraction
│ │ │ ├── generate.py # wiki generation
│ │ │ └── hooks.py # post-commit + install-hooks
│ │ ├── core/
│ │ │ ├── secrin_yml.py # .secrin.yml loader/writer
│ │ │ ├── parser.py # Tree-sitter AST parser (py/ts/js/tsx/jsx)
│ │ │ ├── cloner.py # Git repo cloner
│ │ │ └── config.py # Legacy .secrin/config.yaml
│ │ ├── graph/
│ │ │ ├── neo4j_client.py # Neo4j driver wrapper
│ │ │ ├── builder.py # Batch graph construction (UNWIND MERGE)
│ │ │ ├── schema.py # Constraints + vector indexes
│ │ │ └── diff.py # Incremental update engine (git-diff aware)
│ │ └── search/
│ │ ├── vector_search.py # Neo4j KNN vector search
│ │ ├── graph_search.py # 1-hop Cypher traversal
│ │ └── hybrid.py # Vector + graph merge + re-rank
│ └── config/
│ └── settings.py # Pydantic settings (env / .env)
└── docker-compose.yml # Neo4j + Qdrant + Redis

Neo4j schema

Node labels:Module · File · Class · Function · DomainEntity

Relationships:

Relationship	From → To	Meaning
`CONTAINS`	Module → File	File belongs to module
`DEFINES`	File → Class / Function	File declares the node
`CONTAINS`	Class → Function	Method belongs to class
`CALLS`	Function → Function	Direct call edge
`IMPORTS`	File → File	Import/require dependency
`INHERITS`	Class → Class	Inheritance (Python)
`IMPLEMENTS_DOMAIN`	Any → DomainEntity	Code implements a business concept

LLM-populated properties (set by secrin analyze):

Property	Type	Description
`summary`	String	Plain-English description
`summary_embedding`	Float[]	Vector for semantic search
`summarized_at`	String	ISO-8601 timestamp

Supported languages

Python · TypeScript · TSX · JavaScript · JSX

Git Hook

Install once per repo, then never think about it again:

secrin install-hooks

After every git commit, Secrin automatically:

Detects changed files via git diff-tree HEAD
Deletes stale Neo4j nodes for changed/deleted files
Re-parses and re-inserts updated files
Re-summarizes and re-embeds new nodes
Regenerates affected module pages + architecture.md

# Uninstall
rm .git/hooks/post-commit

Team Workflow

# One-time per repo (run by one engineer, commit the result)
secrin init
secrin graph build --repo .
secrin analyze
secrin domains
secrin generate
git add .secrin.yml docs/wiki/
git commit -m "feat: add Secrin knowledge graph"
secrin install-hooks
# Every engineer after cloning
git clone https://github.com/your-org/your-repo
secrin init # loads defaults from .secrin.yml, just fill in password
secrin status # verify everything is connected
secrin chat "where should I add the new billing endpoint?"

Shared Neo4j (AuraDB): set the AuraDB URI in .secrin.yml and everyone shares the same up-to-date graph. Only the person running secrin analyze needs an LLM API key.

Contributing

poetry install
poetry run secrin --help
poetry run python scripts/verify.py # check Neo4j + Qdrant + Gateway# Run a specific command
poetry run secrin graph build --repo .
poetry run secrin analyze
poetry run secrin chat "how does X work?"

To add a language, extend packages/cli/core/parser.py with the new tree-sitter binding and add its extension to SUPPORTED_EXTENSIONS.

Open an issue, propose a feature, or jump into the codebase.

Documentation shouldn't be a second job. It should be a side effect of writing good code.

Name		Name	Last commit message	Last commit date
.github		.github
apps/web		apps/web
packages		packages
public		public
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
dump.rdb		dump.rdb
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml

Navigation Menu

Uh oh!

Repository files navigation

Secrin - The living wiki that writes itself

What is Secrin?

Table of Contents

Features

Installation

Local LLM (Ollama)

Cloud LLM

Quick Start

1 — Initialize

2 — Build the graph

3 — Generate summaries and embeddings

4 — Generate the wiki

5 — Search and chat

6 — Check status

Configuration

`.secrin.yml` — team config (commit this)

`.env` — secrets (never commit)

Provider comparison

Commands

Setup & monitoring

Graph pipeline

Wiki

Search & chat

Automation

Architecture

Neo4j schema

Supported languages

Git Hook

Team Workflow

Contributing

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Secrin - The living wiki that writes itself

What is Secrin?

Table of Contents

Features

Installation

Local LLM (Ollama)

Cloud LLM

Quick Start

1 — Initialize

2 — Build the graph

3 — Generate summaries and embeddings

4 — Generate the wiki

5 — Search and chat

6 — Check status

Configuration

.secrin.yml — team config (commit this)

.env — secrets (never commit)

Provider comparison

Commands

Setup & monitoring

Graph pipeline

Wiki

Search & chat

Automation

Architecture

Neo4j schema

Supported languages

Git Hook

Team Workflow

Contributing

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`.secrin.yml` — team config (commit this)

`.env` — secrets (never commit)