Code graph and memory for your coding agents, in one Rust program. For Claude Code, Codex, Cursor and any MCP client.
graphicle-memory: the memory library
graphicle-memory holds the source-backed memory operations that the
graphicle program (crates/graphicle) runs: passage
ingestion, code-structure analysis, retrieval, evidence packing, time and
revisions, and the shared code-graph functions. It is a Rust library with a
bounded JSON interface. It makes no network or model calls: the program that
links it stores the sources, checks authorization and calls any models.
It depends on the graph engine (the graphicle library in
../graphicle-graph) and on no code outside this repository.
This is a selective implementation, not a Rust port of whole applications. Selected algorithms and designs of the projects in NOTICE.md were translated, adapted or reimplemented. UPSTREAM.json records the pinned commits, the inspected files with their hashes and the module that uses each one.
What it does
| Area | Behaviour | Boundary |
|---|---|---|
Source ingestion (ingest, text) |
Exact UTF-8 passages with hashes, token and character bounds, line and byte coordinates and continuation | Storage, transactions and authorization belong to the program that links the library |
Code structure (structure, bindings) |
49 pinned tree-sitter grammars: declarations, imports, calls and their source locations; Markdown links; explicit imported-call binding and lexical shadowing | Generic analyses are incomplete for some languages, and compiler type resolution is not performed |
Retrieval (retrieval, stem, recall) |
BM25 with optional Porter stems, reciprocal rank fusion with the caller's dense results, speaker-scoped ranking, task modes, diversity and explicit evidence needs | Need coverage is lexical; it does not establish semantic completeness or answer correctness |
Evidence packing (packing) |
An exact final token bound, source-first allocation, focused windows, original-source continuation and whole-procedure delivery | Counts with cl100k_base; the answering model's tokenizer may differ |
Time and revisions (temporal, lifecycle) |
Recorded and event clocks, question periods, temporal contradiction previews and historical memory reads | Unknown time stays unknown |
Documents and refresh (document) |
Document blocks, eight delta operations, current-source citations and immutable previews | The agent or model proposes the text; a person reviews it |
Derived state (cache) |
Transitive stale-dependency detection, source-removal propagation and scoped, bounded caches | |
Standing statements (standing) |
A user's standing instructions and preferences, and "I've never" conflicts, found in labelled turns without a model call | |
Code graph (graph) |
Shared identity, document anchoring, canonicalization, stable communities, graph retrieval and cross-repository import linking |
archived lists the options and values that this release does not support: a
request that turns one on gets an explicit error instead of being ignored.
Build and test
The grammar pack compiles its 49 grammars from parser sources in .tslp-root,
at the repository root (see .cargo/config.toml). Prepare them once
per checkout, then build from this folder:
python3 ../graphicle/tools/prepare_parser_sources.py # once per checkout
cargo test --locked --all-targets
cargo clippy --locked --all-targets -- -D warnings
Rust 1.94.1 or newer and a C compiler are needed. After the preparation, builds need no network.
Interfaces
- Rust. The
graphicleprogram calls the library directly. Errors are typed (Error,ErrorKind). - JSON lines.
graphicle-memory --jsonlreads one request per line and writes one response per line, with bounded framing shared with the graph engine. Operations namedgraph.*are forwarded to the engine. - C ABI.
src/lib.rsdefines ABI version 1. The library returns owned bytes that the caller releases withgraphicle_free, passing back the exact pointer and length it received.
Licence
Apache License 2.0 (LICENSE). The notices of the adapted projects
are in NOTICE.md; their licence texts, and those of the grammars
in GRAMMAR_NOTICES.json, are in licenses/.