GPS

Product Introduction

1. Definition: GPS (GitHub Project Symbol) is a local-first, CLI-first memory layer and codebase intelligence tool for AI coding agents. It technically functions as a persistent context engine, building a structured, symbol-anchored graph of a software repository to provide targeted context to AI assistants.
2. Core Value Proposition: GPS exists to solve the persistent amnesia problem in AI-assisted development. It anchors an agent's memory directly to code symbols (functions, classes, methods), ensuring that critical project-specific knowledge—conventions, decisions, gotchas, and test commands—is automatically surfaced before any relevant edit, eliminating repetitive instruction.

Main Features

1. Symbol-Anchored Memory: GPS builds a persistent graph linking code symbols to human-authored knowledge. It parses source code using Tree-sitter (WASM) for TypeScript, JavaScript, and Python, with a regex fallback for eight other languages, to extract symbol definitions, call relationships, and test file mappings. Memory artifacts (notes, invariants, decisions) are attached to these symbols, not dumped into a monolithic file, ensuring relevance.
2. Automated Context Retrieval (gps prepare): Before an agent edits a symbol, running gps prepare <symbol> generates a decision-ready brief. This command queries the local symbol graph and returns a structured output containing the symbol's definition, callers, associated test files, applicable invariants, historical notes from past edits, and a calculated risk score—all in a concise, token-efficient format.
3. Intelligent Memory Capture & Promotion: GPS features a configurable policy for capturing and promoting knowledge. Through MCP (Model Context Protocol) hooks with Claude Code and Codex, or explicit calls in Cursor, it can automatically capture developer corrections. These captured "directives" are classified as notes. A rule-based promotion engine analyzes recurring note clusters and can automatically graduate them into standing invariants—blocking rules stored in .gps/invariants.yml—based on configurable risk gates.
4. Structured Invariants System: Unlike linter rules, GPS invariants are human-authored, YAML-defined rules that encode project-specific operational requirements (e.g., "Refunds over $1000 require finance_approval_id"). They include severity levels (info, warn, block), evidence links, and are scoped to specific symbols or patterns, providing LLM-interpretable guardrails.
5. Lifecycle Integration & MCP Server: GPS provides deep integration for major AI coding environments. For Claude Code, it installs a skill and non-blocking lifecycle hooks (SessionStart, UserPromptSubmit, etc.) that automate index rebuilding, context injection, and session distillation. For all agents, it runs gps serve as a local MCP server, exposing structured tools for context retrieval and memory recording directly within the IDE.

Problems Solved

1. Pain Point: Agent Amnesia Across Sessions. AI coding assistants have no persistent memory between sessions, forcing developers to repeatedly re-explain project rules, conventions, and past decisions, wasting time and introducing consistency errors.
2. Pain Point: Context Overload and Noise. Traditional methods like feeding entire files or relying on a generic CLAUDE.md file provide low signal-to-noise ratios, consuming valuable context tokens with irrelevant information and missing critical, symbol-specific nuances.
3. Target Audience: Senior Developers and Tech Leads who need to encode institutional knowledge and best practices for their teams and AI agents; Full-Stack and Backend Engineers working on complex, established codebases with many hidden rules; Teams adopting AI coding assistants (Claude Code, Codex, Cursor) who want to maximize their efficiency and accuracy.
4. Use Cases: Onboarding New Team Members (Human or AI): GPS serves as the canonical source of "how we work here." Preventing Recurring Bugs: Capturing a hard-won lesson about a flaky API call and automatically surfacing it before the next related edit. Code Review Preparation: Using gps impact and gps doc to understand the blast radius and generate a review document for a pull request. Maintaining Architectural Invariants: Ensuring that every new payment-related function adheres to a manually defined approval invariant.

Unique Advantages

1. Differentiation: Unlike vector-based code search tools (Sverklo, Continue) that return ranked chunks, GPS provides structured, symbol-centric intelligence. Compared to static analysis tools (Semgrep, CodeQL), GPS focuses on project-specific operational knowledge and decisions, not just security patterns. It surpasses simple call-graph tools by integrating human intent (notes, decisions) directly into the structural graph.
2. Key Innovation: The symbol-anchored memory promotion lifecycle. GPS doesn't just store notes; it implements a feedback loop where captured corrections are classified, clustered, and—based on recurrence and risk assessment—automatically promoted into first-class, blocking invariants. This transforms transient corrections into durable, actionable project assets that improve over time.

Frequently Asked Questions (FAQ)

1. How does GPS compare to Claude Code's native memory feature? GPS is agent-agnostic (works with Claude Code, Codex, and Cursor), while Claude's memory is locked to its platform. More importantly, GPS memory is anchored to specific code symbols and files, ensuring context is only surfaced when relevant code is touched, unlike Claude's more conversational or file-based memory. GPS also auto-manages a section of CLAUDE.md based on captured global lessons.
2. Is my code sent to the cloud when using GPS? No. GPS is architected as a local-first CLI tool. All parsing, indexing, and graph operations happen on your local machine. The MCP server runs locally. The only potential external call is an optional --call-api flag for features like gps postmortem, which requires an explicit user opt-in and API key.
3. Can GPS work with any programming language? GPS has a primary, high-accuracy parser using Tree-sitter (WASM) for TypeScript, JavaScript, and Python. It includes a secondary regex-based parser for syntax-aware symbol extraction in Java, C#, Go, Ruby, PHP, and Rust, though with lower precision for complex constructs. Language support is extensible.
4. What happens to TODO comments in my code? The gps learn-todos command (run automatically during setup) scans your codebase for TODO(symbol): and FIXME(symbol): patterns, lifting them into GPS notes anchored to the specified symbol. This makes intentional technical debt discoverable via gps prepare. If the TODO comment is later removed, the corresponding note is pruned.
5. How do I control what GPS automatically captures and promotes? You have full governance via installer flags or .gps/config.yml. The --capture flag (auto/inbox) controls if corrections persist immediately or wait for review. The --promote flag (safe/never/all) controls if recurring notes auto-graduate to invariants, with safe blocking auto-promotion for high-risk topics like payments or security.