FAIM-Nativememory as a graph.
A model-independent research prototype for encoding evidence, relating memory nodes, ranking retrieval candidates, and exposing the paths behind a result. Its native path is deterministic by construction; semantic quality, contradiction handling, and evolution behavior still require controlled evaluation.
The live application is an executable demo for technical review. Do not use it for production data or rely on it for operational decisions. FAIMatrix website documentation is still being checked against the source; this case study pins code references to the reviewed commit below and labels the test evidence by its actual scope.
GitHub lists v0.6.1 as a release rather than a prerelease. “Research alpha” describes the current product stage; it is not GitHub release metadata.
What would an inspectable memory system need to show?
The project investigates whether deterministic text features, explicit graph relations, and visible score components can make selected retrieval decisions easier to examine. This is a research question, not a result already established by the repository.
Memory can preserve incompatible statements.
Treat memory as linked evidence.
A mechanism is not proof of quality.
Compare concrete systems, not category labels.
| DIMENSION | RAG PATTERN | FAIM-NATIVE SOURCE |
|---|---|---|
| Representation | An application may use dense, sparse, or hybrid vectors; the pattern does not prescribe a specific encoder. | Native path: deterministic 240-bucket hashed character n-grams plus 16 numeric features; optional model providers are separate. |
| Memory relations | Graph relations and long-lived memory are application choices around a retrieval pattern. | Source models inheritance, opposition and semantic edges, with graph expansion and bounded neighbourhood APIs. |
| Conflict policy | RAG alone does not define contradiction handling. | Opposition paths exist, while merge bookkeeping shares an edge label and the main core-ranker call omits query opposition input. |
| Mutation over time | RAG alone does not prescribe pruning or memory invention. | A gated evolution path can adjust thresholds, prune candidates, and optionally create co-activation macros. |
| Evidence standard | Depends on the specific implementation and evaluation. | The repository exposes citations, provenance and diagnostics; comparative retrieval quality is not established by the inspected source. |
RAG names a broad retrieval-augmented generation pattern. This table describes one reviewed source snapshot and does not imply that other RAG-based systems lack any listed capability.
Define the system by its code paths.
Several names are research vocabulary. The definitions below describe what the audited source does today, including where a label reaches beyond demonstrated behavior.
FRACTAL
A research label
The implementation builds a hierarchical memory graph and estimates correlation-dimension-style diagnostics. This is not evidence that stored memories follow a fractal law.
ANTISYMMETRIC
A module name
The current operator scores high positive cosine similarity to find near-duplicates. It is not a skew-symmetric matrix operation, and it does not detect contradiction by negative cosine.
INHERITANCE
A parent mixture
A child can inherit weighted fractions from up to eight positive-similarity parents. The fractions sum to one; a cosine residual is stored as a novelty proxy.
DEDUPLICATION
A graph action
The write path chooses a deterministic winner using vector-hash ordering and a node-ID tie-break, then records merge-related graph/event data. The initial write does not itself physically delete the losing node; deletion belongs to a separate evolution/pruning path.
PRUNING
A gated deletion pass
Default candidates must be older than seven days, have at most one touch, meet the similarity threshold, and avoid macro protection. Snapshotting is best-effort, so reversibility is not guaranteed.
SELF-INVENTION
A bounded macro proposal
When enabled and its gates pass, repeated co-activation sets can produce a macro node from member vectors. This is constrained graph construction, not open-ended autonomous learning.
opposition edge kind is used in merge bookkeeping and in graph paths read as opposition. Separating “near-duplicate merge” from “evidence conflict” should be an early research and safety task.Three paths share one graph and evidence boundary.
The source separates ingest, query, and evolution orchestration. The following blueprint is a source-derived system view, not a claim about one deployed topology.
The drawing separates source paths and data services for readability. It does not imply a single mandatory deployment profile or that optional provider paths are enabled in the public demo.
From source to stored node
Recall, rank, explain
Measure, gate, mutate
A gated cycle with bounded actions.
The default cycle caps actions at 25, scales that limit within a bounded range using λ, adapts merge and prune thresholds from graph diagnostics, and skips work when its configured gate fails. Macro invention is flag-controlled. A pre-delete snapshot is attempted, but snapshot failure does not block the deletion path.
Seven declared services.
PostgreSQL 15, Redis 7, Qdrant, migration, API, worker, and frontend. This is the repository’s Compose definition; it does not establish that the public demo runs this exact topology or that it meets production service requirements.
The native path uses explicit arithmetic.
The equations below summarize source defaults and contracts. They are engineering rules and proxies; none is presented as a calibrated probability or a theorem about memory quality.
Deterministic text representation
v = normalize₍₂₄₀₎(hash₍3,4,5₎(x)) ∥ s₁₆(x) ∈ ℝ²⁵⁶After Unicode and whitespace normalization, character 3-, 4-, and 5-grams are SHA-256 hashed into 240 buckets. That subvector is L2-normalized, then concatenated with 16 numeric text statistics.
The complete 256D vector is not normalized again in this path. Hashed character features are deterministic lexical/statistical features with collisions; they are not a learned semantic embedding. Optional embedding and OCR providers are separate paths.
Inheritance and residual novelty
wᵢ = sim(v,pᵢ) / Σⱼ sim(v,pⱼ) ; r = clip[0,1](1 − cos(v, Σᵢ wᵢpᵢ))Candidate parents are sorted by cosine similarity, limited to at most eight, and retained only when similarity is positive. Fractions are rounded with a final adjustment so their sum is one.
The residual is a geometric fit proxy against the weighted parent mixture. It is not a semantic novelty score validated against human labels. With no eligible parent, the implementation returns residual 1.
Default core retrieval score
S = .40·sim + .15·nov − .10·opp − .10·red + .10·rec + .10·log(1+touch)/10 − .05·levelThe default weights combine cosine similarity, stored residual novelty, query opposition overlap, redundancy, seven-day access recency, touch count, and graph level. Conditional lexical, graph, modality, domain, reranker, and late-interaction layers can add to this core score.
Source-review finding: the primary rerank_faim call does not pass a query-opposition signature, so the core opposition penalty is zero in that path. Graph opposition handling exists separately; the score formula alone should not be described as active contradiction detection.
Graph diagnostics and evolution pressure
λ = .50·N + .30·(1−R) + .20·ĤN is mean stored residual; R is the fraction of vector pairs above the configured high-similarity threshold; Ĥ is normalized Shannon entropy over the pair-similarity histogram.
D̂ estimates a slope from log-count/log-scale values, in the style of a correlation dimension. E = s · mean(||vᵢ||₂), with default s = 1/φ, is a descriptive energy value. These measurements have not been established as predictors of memory quality or stability.
Macro invention from co-activation
vₘ = normalize(mean(vᵢ : i ∈ M)) ; wᵢ = 1/|M|When self-invention is enabled, a repeated co-activation set may become a macro node. Its vector is the normalized mean of member vectors, its parents receive equal fractions, and its level is one above the highest parent level.
Default gates include λ ≥ 0.30, at least three occurrences, and an estimated redundancy reduction of at least 0.01. A maximum-macro limit and a separate synthesis-invention flag further bound the path.
A transparent rule can still be a weak rule.
A formula makes a decision inspectable. It does not demonstrate that the chosen features represent meaning, that thresholds transfer across domains, or that system behavior improves against a baseline. Those are evaluation questions for the next research phase.
The sketch above is synthetic and illustrative. It shows a possible node and relation pattern, not live user data or an exported FIG capture.
A 3D inspection surface over bounded graph APIs.
FIG View connects a force-directed 3D canvas to graph surface, neighborhood, explain-path, and event endpoints. The visualization is useful for inspection, but the request caps and timeline model matter when interpreting it.
Explore, analyze, and inspect lineage
Three bounded graph reads
GET /graph/surface— default 200 nodes and 800 edges; maxima 500 and 2,000.GET /graph/neighborhood— BFS from a selected node; default depth 2, max depth 4, with node and edge caps.POST /graph/paths/explain— bounded undirected path search; default 12 hops, maximum 32.
Surface: returns capped nodes and edges, graph version, topology counts, and a truncation flag. Edge results are restricted to the selected node surface.
Neighborhood: traverses incident allowed edge kinds breadth-first from a seed node. It reports distances and whether node/edge caps truncated the response.
Timeline: the API returns bounded event sequence numbers, timestamps, kinds, and payload keys. The client filters graph elements by created_at; it does not replay each event into a complete historical graph state.
Who can review the prototype, and what can they inspect?
The current demonstration is suited to engineering and research review with synthetic or non-sensitive data. The diagram separates implemented inspection paths from a benchmark capability that still needs reproducible evidence.
Controls exist in code; assurance is still open.
The repository contains tenant context, scoped API keys, idempotent writes, optional storage encryption, and audit routes. A code path is evidence of implementation, not an independent security assessment or production guarantee.
Key lifecycle is tenant-scoped
Scope enforcement is configurable
Tenant filters reach repositories
Retries have an idempotency boundary
Data and service layout
Compose describes PostgreSQL 15, Redis 7, Qdrant, migration, API, worker, and frontend services. PostgreSQL stores graph and state records; vector search can use Qdrant with an in-memory brute-force fallback; Redis supports cache, locks, and worker-side paths. Raw-store envelope encryption is optional.
Before any external preview
Test auth and scope failures, cross-tenant negative cases, key rotation/revocation, backup/restore, event replay, deletion recovery, resource limits, and demo-data isolation on the exact release candidate. A threat model and independent review remain future work.
Separate repository facts from reported execution.
Counts below describe the reviewed source tree. The local pytest result was supplied separately and has no source revision attached, so it is not represented as a run of the pinned snapshot.
Source inventory and reported run, with commit scope stated.
Research alpha · GitHub v0.6.1 · 202 test files · 41 migrations
The public main source snapshot audited for this page is commit 869b4fda633002c611efc9b3172bef9f6721b22a from 2026-09-10. A static inventory at that SHA found 202 Python test-named files under tests/, 297 Python files under faim_native/, 41 numbered PostgreSQL migrations, and a 256-dimensional native vector constant in source. Separately, the supplied local pytest report states 1,009 passed, 1 skipped, and 500 warnings; its checkout SHA was not provided, so it is not attributed to this snapshot.
GitHub main snapshot dated 2026-09-10; source links above are pinned here
Latest release found during the audit; GitHub does not mark it as a prerelease
Python files named as tests under tests/ at the audited SHA
Python files under faim_native/ at the audited SHA
Numbered SQL migrations at the audited SHA
Dimension constant implemented by the native vectorizer
Supplied report: 1 skipped, 500 warnings; checkout SHA unknown
No pytest CI result for the audited main SHA was found
Supplied report lists Ruff/MyPy findings; Bandit unavailable in that environment
Working demo prototype for review; not ready for operational use
EVIDENCE_NOTE:: The 1,009-test result is user-supplied, not independently reproduced, and not linked to a commit or CI run. The latest visible main workflow was a successful deployment workflow, not a pytest result. Ruff/MyPy findings and Bandit unavailability come from the supplied local report and were not rerun here. The project is an active research alpha and demo prototype, not ready for operational use or production data; website documentation accuracy is still being reviewed.
Pinned implementation review
A supplied result, not a reproduced run
No performance or readiness claim
Set clear evidence gates for a public preview.
The stages below are recommended engineering and research gates. They are not a committed schedule or a claim that each gate is already complete.
Resolve semantics and invariants
- Give near-duplicate merges and factual opposition distinct edge and event types; specify what each relation means and how it changes retrieval.
- Route a real query-opposition signature into the core scorer or remove the inactive penalty from the claimed path; cover it with focused tests.
- Specify merge, restore, and prune invariants, including provenance retention, winner selection, idempotent replay, and failure recovery.
Measure retrieval and conflict behavior
- Freeze a small, versioned corpus with paraphrases, duplicates, explicit contradictions, changed facts, timestamps, and source provenance.
- Compare native retrieval with lexical/BM25 and a documented dense or hybrid baseline under the same corpus, top-k, and compute budget.
- Report Recall@k, MRR or nDCG, contradiction precision/recall, citation support accuracy, calibration, latency percentiles, and failure examples.
- Publish seeds, manifests, environment versions, raw outputs, and ablations for inheritance, graph expansion, fusion layers, and evolution gates.
Prepare a reviewable public preview
- Exercise fail-closed authentication and scopes, tenant isolation, key expiry/revocation, rate limits, and idempotent writes against a dedicated demo dataset.
- Verify migrations, backup/restore, deletion behavior, event integrity, observability, resource limits, and dependency/license inventory.
- Reconcile website documentation with the running code; publish known limits, setup steps, demo-data policy, and a versioned verification record.
- Run the complete CI suite and security checks on the exact preview commit, then label the release as pre-release if that is the chosen distribution state.
Open the code behind the method and diagrams.
Every link below is pinned to the audited commit 869b4fda633002c611efc9b3172bef9f6721b22a. The links make the implementation review repeatable even if the repository’s main branch changes later.
DOCUMENTATION IN PROGRESSThe repository reports are an evolving engineering archive. The “Completed” folder can contain historical material; its status and validation statements are not independent proof of current behavior. Check the pinned source links below against the code.
faim_native/encoding/text_vectorizer.pyInheritance weights and residualfaim_native/core/operators/inheritance.pySimilarity merge operatorfaim_native/core/antisym.pyFractal diagnosticsfaim_native/core/metrics/fractal_physics.pyEvolution gates and actionsfaim_native/core/dynamics/evolution_native.pyMacro inventionfaim_native/core/dynamics/invention_native.pyPruning policyfaim_native/core/operators/prune.pyRetrieval score and fusionfaim_native/core/query/query_engine.pyGraph conflict semanticsfaim_native/core/query/graph_semantics.pyAnswer and evidence synthesisfaim_native/core/query/answer_synthesis.pyIngestion orchestrationfaim_native/orchestration/ingest_flow.pyQuery orchestrationfaim_native/orchestration/query_flow.pyFIG graph APIfaim_native/api/routers/graph.pyFIG graph traversalfaim_native/api/fig_graph_core.pyFIG View page and controlsfrontend/src/components/graph/FigViewPage.tsxFIG 3D canvasfrontend/src/components/graph/FigCanvas.tsxGraph node repositoryfaim_native/store/pg/repos/node_repo.pyAPI key lifecyclefaim_native/api/routers/api_keys.pyREADME architecture and lifecycle diagramsREADME.md