Metadata-Version: 2.4
Name: glia-memory
Version: 0.6.1
Summary: Persistent holographic distributed memory for AI agents
Author: Felipe Farías Alfaro
License-Expression: MIT
Project-URL: Homepage, https://github.com/FelipeFariasAlfaro/glia
Project-URL: Repository, https://github.com/FelipeFariasAlfaro/glia
Project-URL: Issues, https://github.com/FelipeFariasAlfaro/glia/issues
Keywords: memory,ai,agents,holographic-memory,hdm,vsa,resonance,mcp
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: numpy>=1.24
Requires-Dist: sentence-transformers==5.6.1
Requires-Dist: python-dotenv>=1.0
Requires-Dist: mcp>=1.0
Requires-Dist: watchdog>=3.0.0
Provides-Extra: fastembed
Requires-Dist: fastembed>=0.8.0; extra == "fastembed"
Provides-Extra: gemini
Requires-Dist: google-genai==2.12.0; extra == "gemini"
Provides-Extra: build-binary
Requires-Dist: pyinstaller==6.16.0; extra == "build-binary"
Provides-Extra: test
Requires-Dist: pytest==9.1.1; extra == "test"
Dynamic: license-file

# GLIA: Holographic Distributed Memory for AI Agents

[Read in Spanish](README_ES.md) | [Changelog](CHANGELOG.md)

Current release target: `0.6.1` (unreleased).

GLIA is a persistent memory system for AI agents based on Holographic Distributed Memory (HDM). It stores knowledge as distributed high-dimensional patterns, retrieves it by resonance, and encodes relationships as reversible holographic contributions. It is not a graph database, a BM25 index, or a conventional RAG pipeline.

GLIA is designed for agents that need durable project context: architectural decisions, code structure, source provenance, operational knowledge, and bounded memory adaptation across sessions.

## What GLIA does

- Encodes text and code deterministically into 1024-dimensional vectors without requiring an API key.
- Stores glyphs in superposed memory regions and scores them through parallel vector resonance.
- Encodes associations through circular binding and explicit, reversible relationship contributions rather than graph edges.
- Scans supported source files incrementally, tracks source hashes, and removes contributions for deleted or ignored files.
- Provides stable, read-only recall by default; optional `adapt` persists bounded Hebbian reinforcement and optional `explore` reserves results for holographic associations.
- Persists project memory in SQLite with WAL, full synchronous durability, optimistic revisions, validation, backups, and recovery from transient lock contention.

## Core model

```text
source text or code
        |
        v
 deterministic encoding
        |
        v
 glyph vector + metadata
        |
        v
 superposition in a region
        |
        +-- reversible bound relationship contributions
        |
        v
 resonance against a query vector
        |
        v
 ranked glyphs, sources, and cognitive context
```

A region is the sum of each glyph vector weighted by its magnitude plus its relationship contributions. This invariant is validated before every persistent commit. Glyphs, relationships, and regions managed by the substrate expose immutable vector data; supported mutation APIs preserve regional superposition atomically.

GLIA still persists glyph metadata to support provenance, ranking, source removal, and exact recovery. Region vectors have fixed dimension, while the total durable footprint includes glyph and relationship metadata. It does not claim constant total database size as memory grows.

## Reliability and scalability

The current implementation focuses on predictable behavior under failures, concurrent writers, and growing memory.

- SQLite commits use optimistic revisions. A stale writer is rejected rather than overwriting newer knowledge.
- `GliaBrain` reloads and reapplies deterministic mutations after revision conflicts.
- `BEGIN IMMEDIATE` retries transient `SQLITE_BUSY` and `SQLITE_LOCKED` errors with bounded backoff.
- Normal GLIA operations persist tracked deltas and source deletions; direct storage callers retain exact-membership reconciliation for defensive integrations.
- Full SQLite/vector validation remains available on load and through `glia doctor --deep`; normal commits validate changed payloads without reconstructing every untouched region.
- Scanner updates and scan-state changes are committed atomically. Per-file scanner failures restore prior source contributions and tracking state.
- Resonance uses an immutable cached vector matrix. Repeated queries avoid rebuilding the matrix; supported mutations invalidate the cache.
- Backups use SQLite's backup API and are published atomically with unique names.

## Installation

Requirements:

- Python 3.11 or newer
- NumPy and local Sentence Transformers embeddings (installed with GLIA)
- Git for optional post-commit integration
- The optional `gemini` extra and a Gemini API key only for remote distillation or embeddings

```bash
cd ~/tools
git clone https://github.com/FelipeFariasAlfaro/glia.git
cd glia
python -m venv .venv
.venv/bin/pip install -e .
.venv/bin/glia --help
```

### Standalone binaries (no Python required)

Projects that are not Python-based can use a self-contained binary from the
[GitHub Releases](https://github.com/FelipeFariasAlfaro/glia/releases) page.
No `python`, `pip`, or virtual environment is needed; download, make it
executable, and run it.

| Variant | Embeddings | Size | Best for |
|---|---|---|---|
| `glia-light` | ONNX via fastembed | small | most users and non-Python projects |
| `glia-full` | Sentence Transformers | large | maximum semantic quality |
| pip (`glia-memory`) | configurable | — | Python users |

The recommended convention is to place the binary inside the project's `.glia/`
folder under the fixed name `glia`, so the MCP configuration is identical across
machines and the binary stays out of version control:

```bash
mkdir -p .glia
# download the build for your platform into .glia/ and rename it to glia
mv glia-light-linux-x86_64 .glia/glia
chmod +x .glia/glia

.glia/glia init
.glia/glia scan
.glia/glia mcp   # run the MCP server over stdio
```

Both variants bundle their own SQLite and embedding runtime. The embedding
model itself downloads on first use. `.glia/` is git-ignored, so the binary is
never committed and each machine downloads its own platform build. Point your
MCP client's `command` at `.glia/glia` and pass `["mcp"]` as `args`:

```json
{
  "mcpServers": {
    "glia": {
      "command": ".glia/glia",
      "args": ["mcp"],
      "env": { "GLIA_WORKSPACE": "." },
      "disabled": false
    }
  }
}
```

## Quick start

Run these commands inside the project you want GLIA to remember.

```bash
# Initialize the local durable memory
python -m glia init

# .glia/ now includes GLIA_GUIDE.md and GLIA_GUIDE_ES.md.
# Scan supported source and documentation files
python -m glia scan

# Stable read-only recall
python -m glia recall "authentication session token"

# Explicit bounded adaptation
python -m glia recall "authentication session token" --adapt

# Explicit holographic association exploration
python -m glia recall "authentication session token" --explore

# Inspect durable storage
python -m glia doctor --deep
```

`recall` is read-only by default. Use `--adapt` only when reinforcement should be persisted. Use `--explore` only when association discovery is desired; stable ranking does not mix unbinding evidence into its primary results.

GLIA is local-first: scans, recall, MCP, and `glia learn` run locally by default, with local semantic embeddings included in the standard installation. No API key or remote provider is required.

### Local semantic embeddings

`pip install glia-memory` includes the local Sentence Transformers provider and uses it by default. The default multilingual model returns 1024-dimensional vectors, matching GLIA's memory dimension:

```text
GLIA_EMBEDDING_PROVIDER=sentence-transformers
GLIA_EMBEDDING_MODEL=intfloat/multilingual-e5-large
```

The model downloads only on first use unless `GLIA_EMBEDDING_MODEL` is a local directory or is already in the Hugging Face cache.

For a lighter local option without PyTorch, use the ONNX-based `fastembed` provider (the default of the light binary). Install the extra with `pip install "glia-memory[fastembed]"`:

```text
GLIA_EMBEDDING_PROVIDER=fastembed
```

For an ultra-lightweight, model-free mode, explicitly select deterministic encoding:

```text
GLIA_EMBEDDING_PROVIDER=deterministic
```

### Optional Gemini support

Gemini is an optional extra for LLM distillation and remote embeddings:

```bash
pip install "glia-memory[gemini]"
```

```text
GEMINI_API_KEY=your_key_here
GLIA_MODEL=gemini-3.1-flash-lite-preview
GLIA_EMBEDDING_PROVIDER=gemini
GLIA_EMBEDDINGS_ENABLED=true
GLIA_EMBEDDING_MODEL=gemini-embedding-001
```

Use `glia learn --online "..."` only when LLM-assisted distillation is intended. The default `glia learn "..."` and `glia learn --offline "..."` stay local.

## CLI and MCP

Useful CLI commands include:

| Command | Purpose |
|---|---|
| `python -m glia init` | Create project-local `.glia` storage |
| `python -m glia scan` | Incrementally scan the project |
| `python -m glia sync` | Apply detected changes/deletions atomically |
| `python -m glia recall "query"` | Retrieve stable resonance results |
| `python -m glia recall "query" --adapt` | Persist bounded reinforcement |
| `python -m glia recall "query" --explore` | Include holographic association exploration |
| `python -m glia learn "text"` | Store knowledge through deterministic local distillation |
| `python -m glia learn --online "text"` | Use the optional configured LLM provider |
| `python -m glia forget` | Apply temporal decay |
| `python -m glia stats` | Report memory statistics |
| `python -m glia doctor --deep` | Run SQLite integrity checks |
| `python -m glia backup` | Create a durable SQLite backup |

GLIA also exposes an MCP server. Configure your client to run `python -m glia.mcp_server` and set `GLIA_WORKSPACE` to the target project. The server does not scan on startup. `glia_detect_changes` and `glia_recall` without `adapt=true` are read-only; `glia_sync`, `glia_scan`, `glia_learn`, `glia_learn_file`, `glia_forget`, and adaptive recall are explicit mutations. Tool results are structured and include provenance, revision, and diagnostics. All requested source paths are restricted to `GLIA_WORKSPACE`.

### Python integration

Use the public `MemoryClient` facade when integrating an application or custom agent:

```python
from glia import Document, MemoryClient

memory = MemoryClient.open("/path/to/project")
memory.ingest([Document(source="runbook/auth", content="Session tokens expire in seconds.")])
result = memory.recall("How does session expiry work?")
for hit in result.hits:
    print(hit.source, hit.score, hit.content)
```

`Document` ingestion is source-idempotent in offline mode; it replaces prior contributions from the same source. Implementations can supply an `EmbeddingProvider` with `provider`, `model`, `dimension`, `is_available`, `embed`, and `embed_batch` when using a provider other than the built-in Gemini adapter.

## Supported extraction

The scanner extracts useful structure from Python, JavaScript, TypeScript, Java, Go, Rust, C#, C/C++, Ruby, PHP, Kotlin, Swift, Gherkin, Markdown, text, and common configuration files. It uses source-qualified identities so files with the same basename do not collide.

## Benchmarks

The reproducible phase-2 benchmark compares GLIA with direct HDM retrieval, Okapi BM25, and SQLite FTS5 on versioned relevance judgments. It also measures persistence and query scaling locally.

Run it with:

```bash
.venv/bin/python benchmarks/benchmark_phase2.py --sizes 100 1000 5000 --query-count 10
```

Final phase-3 local results at 5,000 glyphs:

| Metric | Result |
|---|---:|
| Initial full save | 180.08 ms |
| Validated incremental save of one glyph | 26.26 ms |
| Rows changed by that incremental save | 1 region and 1 glyph |
| Cold query, including matrix construction | 32.13 ms |
| Warm cached query | 6.10 ms |
| Stable public recall | 7.10 ms |
| Adaptive recall | 65.13 ms |
| SQLite database, WAL, and SHM footprint | 86,047 KiB |

Retrieval MRR in the same benchmark was 0.837 for the backend fixture, 0.802 for the ML fixture, and 0.776 for the TypeScript/React fixture. BM25 and FTS5 remain stronger and faster lexical baselines for exact-term retrieval; GLIA's differentiated value is persistent HDM resonance, reversible binding, bounded plasticity, source-aware scanning, and association exploration.

Benchmark timings depend on hardware and process state. Quality is measured against versioned query relevance judgments rather than inferred during the run.

## Operational notes

- Add `.glia/` to the target project's `.gitignore` unless you intentionally share its memory database.
- Do not edit SQLite files while an MCP server or CLI operation is writing. GLIA retries transient locks, but long external write transactions should be avoided.
- Use `glia doctor --deep` when diagnosing persistence concerns.
- Use `glia backup` before moving, manually inspecting, or recovering project memory.
- If an MCP server still runs old code after an upgrade, reconnect it from the MCP client.

## License

GLIA is distributed under the [MIT License](LICENSE).
