Engineering practices

Engineering Practices

The design philosophy and engineering standard behind CodeMind Graph: AI-native workflows, local-first processing, deterministic knowledge graphs, and read-only MCP integration.

Engineering practices

AI-native, local-first engineering standards

CodeMind Graph treats structured context as a first-class engineering artifact. The product is built around deterministic graphs, privacy-preserving local processing, and read-only agent integration.

AI-first development

The repository is shaped for agents as well as humans: commands are deterministic, outputs are diffable, and context is structured.

Local-first processing

Source analysis runs on the developer machine. Generated graph data stays local unless the owner explicitly publishes a public demo.

Privacy-first architecture

MCP tools are read-only by default and do not expose session notes, private docs, environment variables, or write operations.

Source of truth management

The persisted graph, repo map, and docs-as-state files make long-running engineering sessions resumable and auditable.

Architecture

Architecture standard

The v0.1 architecture starts with a TypeScript Compiler API adapter, a deterministic core graph model, a CLI-first query surface, and a read-only MCP server.

Knowledge Graph RuntimeRepresent files, modules, symbols, imports, exports, and traces as stable nodes and edges.
AI-native WorkflowGive implementer, evaluator, and reviewer agents the same structured context before they act.
Persistent Context SystemUse generated repo maps and project state docs as handoff artifacts for long engineering sessions.
Graph-based Code IntelligencePrefer deterministic symbol navigation over approximate raw-file prompting for architecture work.

Standards

Operational standards

Deterministic output

Index, find, trace, map, and MCP responses must remain stable enough for tests, reviews, and diffs.

Read-only agent boundary

The MCP server can retrieve graph context, but it cannot edit files, run shells, install packages, or leak secrets.

Agent-friendly context design

Public product content explains the graph model without publishing private `.codemind/` data or engineering memory.

Quality gate

Changes that affect the website, graph queries, or MCP protocol must pass the relevant build, test, and browser QA workflow.

Why CodeMind Graph

AI coding agents need more than raw files

Large repositories overwhelm context windows, hide architecture behind file trees, and lose decisions between sessions. CodeMind Graph turns repository structure into a persistent knowledge layer that both humans and agents can inspect.

Limits

Context windows fragment

A model can read a few files, but it rarely keeps the whole dependency story in view during long-running engineering work.

RAG alone is approximate

Similarity search helps discovery, but it does not provide deterministic symbol ownership, import paths, or module boundaries.

Project memory drifts

Decisions, generated maps, and handoff state become unreliable when they are not grounded in the current repository graph.

CodeMind Graph

Knowledge graph

Files, modules, symbols, imports, exports, and traces become addressable graph entities instead of loose text chunks.

Local-first runtime

Repository intelligence is generated locally and stored under `.codemind/`, preserving privacy and low-latency lookup.

Persistent engineering memory

Repo maps and read-only MCP tools give agents stable context across sessions without exposing private engineering notes.

Brand positioning

A code knowledge graph platform, not another document layer

CodeMind Graph is designed for large repositories, AI agents, and persistent engineering work. It combines graph-driven code intelligence with local-first safety.

Not
  • Not a generic document tool
  • Not only a vector database
  • Not a raw RAG wrapper
Is
  • AI-native code knowledge graph
  • Local-first repository intelligence layer
  • Graph-driven context system for long-running agents