| --- |
| language: en |
| license: mit |
| library_name: revision-memory |
| tags: |
| - vector-symbolic-architectures |
| - hyperdimensional-computing |
| - holographic-memory |
| - reasoning |
| - forward-chaining |
| - belief-revision |
| - truth-maintenance |
| - non-monotonic-reasoning |
| - knowledge-representation |
| - numpy |
| - custom-library |
| pipeline_tag: feature-extraction |
| datasets: [] |
| metrics: |
| - accuracy |
| model-index: |
| - name: revision-memory |
| results: |
| - task: |
| type: feature-extraction |
| name: Belief revision and derivational reasoning |
| dataset: |
| type: custom |
| name: Synthetic chain, tree, and multipath graphs |
| config: None |
| split: test |
| revision: main |
| metrics: |
| - type: accuracy |
| value: 1.0 |
| name: Chain closure exactness (10-node chain) |
| - type: accuracy |
| value: 1.0 |
| name: Multipath derivation survival |
| - type: accuracy |
| value: 1.0 |
| name: Derived edge removal without trace damage |
| --- |
| |
| # revision-memory |
|
|
| Belief revision with derivation-tracked cascade in a phasor memory. |
| Assert facts, derive their consequences, retract a source, and re-derive — |
| all in one complex-valued trace. |
|
|
| The memory stores edges as directed bindings in a phase-only holographic |
| substrate. `derive()` computes the transitive closure up to a fixpoint. |
| Every derived edge knows its parents. `forget()` removes an asserted |
| edge and rebuilds the trace from whatever remains. |
|
|
| ## Install |
|
|
| ```bash |
| pip install numpy |
| # copy revision_memory.py into your project |
| ``` |
|
|
| ## Usage |
|
|
| ```python |
| from revision_memory import RevisionMemory |
| |
| mem = RevisionMemory(D=1024) |
| |
| # assert a chain |
| for a, b in [("a","b"), ("b","c"), ("c","d"), ("d","e")]: |
| mem.assert_edge(a, b) |
| |
| # derive the closure |
| mem.derive() |
| # edges now include a→c, a→d, a→e, b→d, b→e, c→e |
| |
| # query the substrate directly |
| mem.query("a", "e") # +0.31 |
| mem.chain("a") # ['a', 'b', 'c', 'd', 'e'] |
| |
| # explain a derived edge |
| mem.explain("a", "e") |
| # {'edge': ('a','e'), 'kind': 'derived', 'weight': 1.0, |
| # 'via': [{'edge': ('a','c'), ...}, {'edge': ('c','e'), ...}]} |
| |
| # retract a source |
| mem.forget("b", "c") |
| # a→c, b→d, b→e are gone; a→b, c→d, d→e remain |
| |
| # re-assert and re-derive |
| mem.assert_edge("b", "c") |
| mem.derive() |
| # full closure restored |
| ``` |
|
|
| ## What this module does |
|
|
| ### Assert → derive → retract → re-derive |
|
|
| The cycle is the point. Every stored edge is either **asserted** (the user |
| put it there) or **derived** (the system computed it). When an asserted |
| edge is removed, the trace is rebuilt from the remaining assertions, and |
| derivation runs again. |
|
|
| ### Derivation with dependency tracking |
|
|
| Each derived edge records the two edges it was composed from. The |
| `explain()` method returns the full derivation tree, back to the original |
| assertions. No black box. |
|
|
| ### Weight propagation |
|
|
| Assertions carry weights in `[0, 1]`. A derived edge's weight is the |
| **minimum** over all derivation paths. Weak links degrade the derivation |
| monotonically. `explain()` reports the weights at each level. |
|
|
| ### Multi-path survival |
|
|
| If two routes derive the same edge, removing one route leaves the edge |
| derived via the other. The trace-level derivation is robust to |
| single-assertion removal when redundancy exists. |
|
|
| ## Benchmarks |
|
|
| | Experiment | Result | |
| |---|---| |
| | Chain closure (10 nodes, 9 assertions) | 45/45 edges derived (exact) | |
| | Multipath derivation survives removal | a→c persists after removing a→b | |
| | Chain quality degrades gracefully | 0.174 → 0.073 with 100 noise edges | |
| | Explainability | Full derivation tree returned | |
| | Weighted derivation | min(parent weights), monotone | |
| | Scaling to depth 18 | 153/153 edges, quality 0.070 | |
|
|
| ## Architecture |
|
|
| Vectors are complex phasors of dimension D, unit modulus. Binding is |
| `bind_dir(a, b) = a · roll(b, 1)` — non-commutative, so order matters. |
| The trace is a weighted sum of directed bindings: |
|
|
| ``` |
| trace = Σ w_i · bind_dir(node_a, node_b) |
| ``` |
|
|
| Queries unbind in the frequency domain: |
|
|
| ``` |
| u = unbind_dir(node_a, trace) # ≈ Σ w_i · node_b |
| ``` |
|
|
| Similarity is complex cosine. The substrate is O(D) per operation, no |
| FFT, no matrix multiplication. |
|
|
| ## What it does not do |
|
|
| - **No control flow, no negation, no cycles that terminate cleanly.** The |
| derivation is transitive closure only. Cycles derive indefinitely |
| without a `max_rounds` guard (which the implementation provides). |
| - **Not a general reasoner.** This is forward chaining on a directed |
| graph. No unification, no variables, no pattern matching. |
| - **Derived edges compete with asserted edges in the walk.** A chain can |
| skip steps because a derived shortcut reads at the same strength as a |
| direct assertion. See `test_1_basic` in the source for the behavior. |
| - **Capacity bounded by K_max ≈ D^0.907.** At D=2048, roughly 560 edges |
| before retrieval accuracy drops below 90%. For larger graphs, raise D. |
| - **No persistence of derived state.** `save_pretrained` is not |
| implemented in this version. The trace and assertions are in memory |
| only. |
| |
| ## Intended use |
| |
| - **Belief revision in an agent.** The agent asserts facts, derives |
| consequences, and retracts when new information arrives. The trace |
| rebuilds automatically. |
| - **Truth maintenance.** Every derived edge carries its parents. When |
| a source is removed, the cascade is tracked. |
| - **Explainable reasoning.** `explain()` returns a tree that a |
| downstream user can inspect. |
| - **Neuro-symbolic memory.** The substrate is a phasor memory; the |
| reasoning layer is a derivation engine on top. Both share one trace. |
|
|
| ## Out-of-scope use |
|
|
| - **Not for high-stakes reasoning.** Capacity limits are real; the |
| substrate can silently return a wrong answer near K_max. |
| - **Not for cryptographic security.** Anyone with the trace and the |
| node identifiers can attempt reconstruction. |
| - **Not a replacement for a database.** Concurrency, transactions, and |
| durability are not implemented. |
| |
| ## Limitations |
| |
| - **Trace rebuild cost.** `forget()` rebuilds the entire trace from |
| remaining assertions. For N edges, that is O(N · D). Fine up to a |
| few thousand edges; slow beyond. |
| - **No incremental removal.** The trace cannot be updated in place |
| after a retraction without a full rebuild, because the removed edge's |
| consequences are interleaved with all other bindings. |
| - **Derived edges are re-derived from scratch.** On every `forget()`, |
| all derivations are recomputed. This is correct but slow for dense |
| graphs. |
| - **No temporal ordering.** The trace has no notion of when an edge was |
| asserted. All edges exist simultaneously. |
| |
| ## Citation |
| |
| ```bibtex |
| @software{q2026revision, |
| author = {zeechimp}, |
| title = {revision-memory: Belief Revision with Derivation-Tracked Cascade}, |
| year = {2026}, |
| publisher = {Hugging Face}, |
| url = {https://huggingface.co/zeechimp/revision-memory} |
| } |
| ``` |
| |
| ## License |
| |
| MIT |
