Genomefy MCP Server

<p align="center"> <img src="docs/logo.svg" width="420" alt="Genomefy — auditable context memory for AI"> </p>

<p align="center"> <strong>Give your AI less context — and receipts for every choice.</strong> </p>

<p align="center"> <a href="README.md">English</a> · <a href="docs/translations/README.pt-BR.md">Português (Brasil)</a> </p>

<p align="center"> <a href="https://github.com/tallesnicacio/genomefy/actions/workflows/tests.yml"><img src="https://github.com/tallesnicacio/genomefy/actions/workflows/tests.yml/badge.svg" alt="Tests"></a> <img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white" alt="Python 3.11+"> <img src="https://img.shields.io/badge/status-experimental-f59e0b" alt="Experimental"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="Apache-2.0"></a> </p>

Genomefy is a local context-memory layer for AI assistants. It turns project knowledge into small, versioned units, retrieves only the evidence needed for a question, and records exactly why each unit was selected or excluded.

• Local-first, no paid API required. The core uses Python, SQLite and FTS5. Retrieval makes no LLM call.
• Every selected unit carries evidence. Source path, version, SHA-256 hash, confidence and selection reasons travel with the context.
• Every query is replayable. Runs, explicit feedback and memory changes live in an append-only, hash-linked audit trail.

Genomefy borrows names from biology — genes, loci, promoters, repressors, splicing and epigenetic marks — as an interface model. The implementation is conventional software running on ordinary binary hardware.

<p align="center"> <img src="docs/genomefy-hero.svg" width="920" alt="Genomefy turns project memory into a small cited context transcript"> </p>

Get started

git clone https://github.com/tallesnicacio/genomefy.git
cd genomefy
python -m pip install -e .

Create a project-local memory and ingest Markdown or text files:

genomefy --root /path/to/project init
genomefy --root /path/to/project ingest docs docs
genomefy --root /path/to/project query "Why did we choose rotating refresh tokens?" --budget 900

The result is a bounded context transcript:

[GENE gene:auth-decision] Authentication decision
The system uses short-lived signed session tokens and rotates refresh tokens...
[CITATION architecture.md:12 | src:...:v2 | confidence=1.00]

[AUDIT run=run:1781... tokens=107/180 counter=regex-estimate-v1]

Inspect the full decision trail:

genomefy --root /path/to/project audit run:1781...
genomefy --root /path/to/project audit verify

What it promises

Genomefy is designed to test one concrete hypothesis:

A structured, regulated memory can send substantially less context to an AI without materially reducing answer coverage, while keeping citations and retrieval decisions auditable.

The initial success gate is fixed before evaluation:

Metric	Required result
Context-token reduction	≥ 25% against the strongest baseline
Key-fact coverage	no more than 2 percentage points lower
Citation accuracy	≥ 95%
Minimum sample for PASS	30 questions

A smaller suite can be INCONCLUSIVE or FAIL, never PASS.

Current evidence — honest by design

The versioned benchmark suites currently report:

Questions	Comparator	Context reduction	Quality delta	Citation accuracy	Outcome
8	local graph baseline	37.28%	0.00 pp	100%	INCONCLUSIVE
60	full context	92.54%	-4.17 pp	100%	FAIL
60, known-suite post-fix	full context	92.50%	0.00 pp	100%	PASS*

The smoke suite remains INCONCLUSIVE because eight questions are not enough for PASS. The frozen 60-question controlled retrieval suite is a real negative result: token reduction, citation integrity and deterministic stability passed, while the overall quality and worst-category gates failed. Facet-aware retrieval then passed every frozen gate with 100% key-fact coverage on the same suite. PASS* is a post-hoc engineering regression result on a known suite, not independent confirmation. See the original Stage 2 report and post-fix evolution report.

See the benchmark protocol and the machine-readable protocol configuration.

How it works

documents / JSONL / optional Graphify graph
                     │
                     ▼
       versioned genes + loci + relations
                     │
              question + task
                     │
                     ▼
 exact + FTS promoters → graph expansion (≤2 hops)
                     │
                     ▼
 task modifiers + repressors + bounded feedback marks
                     │
                     ▼
 token-budgeted splicing → cited context transcript
                     │
                     ▼
         run record + hash-linked audit event

Biological metaphor	Concrete implementation
Gene	A small, addressable unit of project knowledge
Locus	Stable identity shared by versions of the same subject
Allele	A source version; older versions remain traceable
Promoter	Exact and FTS5 retrieval channels combined with RRF
Repressor	Explicit negative terms, suppression and bounded filters
Splicing	Deterministic selection under a token budget
Epigenetic mark	A bounded ±10% utility modifier from explicit feedback only
Transcript	The final cited context passed to an AI

What you get

Capability	What Genomefy provides
Versioned memory	Changed sources create new versions without silently erasing history
Bounded retrieval	Exact/FTS promoters, reciprocal-rank fusion and graph expansion limited to two hops
Context compiler	Deterministic relevance, novelty and budget selection with inclusion/exclusion reasons
Explicit learning	Only accepted/rejected user feedback changes utility; silence changes nothing
Audit integrity	SHA-256 checks for genes and run transcripts plus an append-only event hash chain
Multiple inputs	Markdown/text, canonical JSONL and optional Graphify graph.json
Multiple interfaces	Python library, CLI, optional local MCP server and Codex skill
Measurement harness	Full-context, local-RAG and local-graph baselines, ablations and 10,000-sample paired bootstrap

Graphify + Genomefy

Graphify maps how knowledge is connected. Genomefy decides which part of that knowledge should become context now, under a budget, with version and feedback history.

genomefy --root /path/to/project ingest graphify graphify-out/graph.json

The adapter is optional. Genomefy works without Graphify installed and the local benchmark's graph_baseline is not presented as an official Graphify benchmark.

Codex skill

From a source checkout:

genomefy skill install --global

In a new Codex session, invoke $genomefy. The default workflow retrieves context, answers with source locations and appends a compact audit summary. It never infers feedback from silence.

Optional MCP server

python -m pip install -e ".[mcp]"
genomefy --root /path/to/project mcp serve

Tools exposed locally: genomefy_query, genomefy_explain, genomefy_feedback and genomefy_status.

DNA Graph

The planned visual layer renders memory as an inspectable double helix: knowledge on one strand, evidence on the other, with selected loci forming a linear “context RNA” transcript. The 2D audit view comes first; 3D is only justified if it improves a measured navigation or comprehension task.

Read the DNA Graph specification.

What it does not promise

• It does not make the underlying model more intelligent.
• It does not make ingested sources true.
• It does not provide infinite or DNA-based physical computation.
• It does not call a small smoke test scientific proof.
• It does not hide inferred, historical or excluded evidence behind a visual metaphor.

Development

Genomefy's core has no required third-party runtime dependency.

python -m pip install -e .
python -m unittest discover -s tests -v
python -m genomefy --root benchmarks/fixtures benchmark run \
  benchmarks/fixtures/smoke-suite.json

See CONTRIBUTING.md and SECURITY.md.

Status

Genomefy 0.2.0 is an experimental but functional release. The storage, facet-aware retrieval, temporal allele selection, replay, audit, benchmark and skill-install paths are implemented and tested. The original controlled 60-question run remains FAIL; the known-suite post-fix regression is PASS with 100% coverage. Independent confirmation, local embeddings, end-to-end answer evaluation, the licensed 300-question suite and DNA Graph UI remain future work.

License

Apache-2.0.