---
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