REQL

REQL is a graph-native, storage-agnostic memory engine for codebases and developer tools. It scans a project, compiles source files and supported documents into a local property graph, and retrieves focused context without mandatory LLM calls.

The purpose of REQL is to give coding agents useful, bounded repository context for making code changes. Instead of forcing an agent to scan the entire project or rely on whatever files happen to fit in the prompt, REQL helps it locate the code, symbols, documents, tests, relations, and provenance that matter for the current task.

This keeps modification work grounded in the project graph: agents can start from compact context, follow important links between files and symbols, avoid missing relevant connections, and reduce token waste from broad source dumps. LLMs can be attached at the edges as optional adapters, but compilation, storage, query, retrieval, analysis, reports, and MCP access work locally.

The graph layer is code-first: projects, directories, files, source fragments, modules, packages, classes, interfaces, functions, methods, imports, dependencies, static-analysis findings, document fragments, communities, hubs, and bridges are stored as explicit nodes and edges with provenance.

At a high level REQL works in five stages:

1. scan a project with configured include/exclude rules and built-in ignores;
2. fingerprint artifacts so unchanged files can be skipped on later runs;
3. parse supported code and document artifacts into deterministic graph records;
4. persist graph nodes, edges, cache entries, compilation runs, and deltas in a local store;
5. answer queries by finding lexical seed nodes, expanding a bounded graph neighborhood, ranking the result, and rendering compact context.

This makes REQL useful as a repository context index and deterministic retrieval layer for coding agents: it narrows the working set before edits, keeps important relationships visible, and stays independent from any one database, model provider, or editor.

Features

• Property graph with nodes, edges, weights, confidence, polarity, and provenance.
• Local block-file persistence with fixed-size pages and compressed records.
• Retrieval with lexical seed nodes, bounded graph expansion, and chain-aware ranking.
• Compact query_memories retrieval with agent-ready memory/source texts plus ranked-node, edge, source, and trace metadata.
• Support for reinforcing and inhibiting edges.
• Salience scoring to rank useful code entities and findings.
• Decay and archival of weak graph records while preserving the audit trail.
• Markdown code graph reports.
• Guided terminal launcher and installable CLI.
• REQL, a small language for querying the graph.
• Compile-time project scanning that registers files as graph artifacts.
• Incremental compilation cache with persistent compilation runs and graph deltas.
• Artifact document parsing for Markdown, plain text, and PDF with graceful fallbacks.
• Code artifact recognition for Python, TS/JS, Go, Rust, Java, C/C++, Ruby, C#, Kotlin, Scala, PHP, Swift, Lua, Zig, PowerShell, Elixir, Julia, Verilog, Fortran, Bash, SQL, Terraform, Apex, Pascal, Razor, and related extensions, with Tree-sitter AST graph extraction for recognized languages.
• Deterministic community detection, hub analysis, and bridge analysis with generic-node penalties.
• Optional dependency-free MCP server for bounded agent context retrieval.
• conf.yaml configuration for scanning, parsing, cache behavior, analysis toggles, and report output.
• Typed Python API.

Documentation

The README gives the project overview and common workflows. The focused documentation lives under docs/:

• Architecture: layers, storage port, compile flow, retrieval, maintenance, and deterministic analysis.
• CLI: command reference for compilation, retrieval, graph queries, exports, configuration, install helpers, and MCP startup.
• Configuration: conf.yaml, overrides, scan rules, cache settings, document ingest, analysis toggles, and loader behavior.
• REQL language: first-class graph commands plus FIND, MATCH, PATH, SEARCH, RETRIEVE, EXPLAIN, filters, and examples.
• Schema: core node records, edge records, code types, and relations used in the graph.
• Storage: block adapter, data locality, compression, inspection, compaction, locking, transactions, and bounded operations.
• Artifact ingestion: supported document inputs, parser behavior, graph output, and graceful fallbacks.
• Code analysis: language support, Tree-sitter parsing, extracted symbols, static-analysis findings, and example queries.
• Incremental compilation: dirty planning, cache entries, deltas, deletion handling, and failure behavior.
• Graph analysis: deterministic communities, hubs, bridge signals, CLI usage, REQL examples, and known analysis limits.
• Reporting: generated Markdown reports and standalone HTML graph export.
• MCP server: stdio/HTTP server startup, tool descriptions, Codex and Claude configuration, workflow, and security notes.
• Extending: storage adapters, extractors, engines, and adding node or edge types.

Requirements

• Python 3.10 or newer.
• watchdog is optional and required only for filesystem monitor mode.

Installation

To work on the project locally:

python -m pip install -e .

To run the tests without an editable install:

PYTHONPATH=src python -m unittest discover -s tests -v

On PowerShell:

$env:PYTHONPATH = "src"
python -m unittest discover -s tests -v

Python Quick Start

from reql import MemoryGraph

graph = MemoryGraph.open(".reql/memory.reql")

try:
    graph.compile_project(".")

    context = graph.query_context("payment service")
    print(context)
finally:
    graph.close()

CLI Usage

The canonical installed command is reql. If --storage is not provided, project and cache commands save data in <build path>/.reql/memory.reql; other commands use ./.reql/memory.reql from the current working directory.

From a source checkout, python cli.py ... is the repository-local CLI entry point. It works without PYTHONPATH changes or an editable install:

python cli.py project compile path/to/project
python cli.py query_context --query "payment service"
python cli.py query_memories --query "payment service" --json

Use python launcher.py for the guided terminal menu:

python launcher.py

Running python launcher.py without arguments opens a guided menu for project compilation, retrieval, REQL queries, reports, MCP setup, and storage management. Use python cli.py ... or the installed reql command for command-line automation.

Compile a repository:

reql project compile path/to/project

Document fragments are parsed structurally when compile.ingest_documents is enabled and can be linked to code symbols, while remaining lower-level source context for query answers. compile.documents controls which document formats are structurally ingested. Ingested documents also pass through a local deterministic processor that ranks language-agnostic terms, records RawEvent observations, creates co-occurrence relations, and connects document terms to code symbols when the document explicitly names them.

Retrieve compact agent-ready memories:

reql query_memories --query "payment service" --limit 8 --json

query_memories is the unified compact retrieval path for agents. It returns deduplicated memory/source text rows and, in JSON mode, includes useful retrieval metadata such as trace_id, seed_node_ids, ranked_nodes, nodes, edges, edge_directions, sources, and counts. Use reql query "RETRIEVE ... RETURN ..." when you need explicit custom REQL columns, and use query_context when an agent needs a synthesized context block with owner targets, snippets, source evidence, or cleanup guidance.

Compose context for an agent:

reql query_context \
  --query "payment service"

reql query_explore \
  --query "payment service serialization" \
  --view owners \
  --view callers \
  --view serialization_paths \
  --json

reql query_graph \
  --query "payment service" \
  --max-depth 2

reql query_memories \
  --query "payment service" \
  --limit 8

query_context returns a compact deterministic context block for an agent. It is informative by default for structure, documents, existence checks, and graph links, with source file/line references and raw-query references in one block. Add --code, --docs, or --test to limit the same query to code, documentation/imported documents, or tests. Add --cleanup for dead-code and unused-symbol cleanup; cleanup output shows only matching StaticAnalysisFinding candidates. Add --json to get compact structured data without duplicated rendered Markdown, including query_mode, scopes, owner_candidates, cleanup_candidates, working_set, and targeted_reads. query_explore returns targeted dependency slices for coding agents: owners, callers, public API surface, serialization paths, docs mentions, and code working-set records. Its code view includes the same usage guidance, snippets, and targeted reads. Use repeated --view flags or shortcuts such as --owners-only, --callers-only, and --serialization-paths-only to reduce token use when a task only needs one chain. query_graph returns an agent-oriented structured subgraph: query seed nodes, expanded nodes and edges up to the requested depth, linked textual sources, generic-node filtering diagnostics, directed incoming/outgoing edge context, and a compact rendered context block. Add --json w