fractal-memory 0.3.0__tar.gz

fractal_memory-0.3.0/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+*.whl
+.eggs/
+dist/
+build/
+
+# Virtual environments
+venv/
+.venv/
+
+# Databases (user data)
+*.db
+*.sqlite3
+
+# Logs
+*.log
+
+# Environment files
+.env
+
+# macOS
+.DS_Store
+
+# Testing / Coverage
+.hypothesis/
+.pytest_cache/
+_playwright/
+.coverage
+htmlcov/
+coverage.xml
+
+# Node
+node_modules/
+
+# IDE
+.idea/
+.vscode/
+
+# MCP config (contains user-specific paths)
+.mcp.json
+
+# Internal docs and experiments (not for public repo)
+internal/
+
+# Claude Code settings (user-specific hooks and config)
+.claude/

fractal_memory-0.3.0/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-04-07
+
+### Added
+
+**Phase 1 — Pioneer**
+- `FractalMemory` core class with async `store()`, `retrieve()`, `session_start()`, `session_end()`
+- 5-level zoom system (L0 tag → L1 label → L2 summary → L3 full → L4 raw)
+- Token-budgeted retrieval: top 200 as labels, top 50 as summaries, top 10 as full context
+- Memory lifecycle: probation → confirmed → permanent → safety-critical
+- Intensity-weighted storage with automatic gating
+- Session bootstrap with prior context injection
+- Sentence-transformer embeddings with cosine similarity scoring
+
+**Phase 2 — Shrub**
+- Association graph: edges form between co-retrieved memories, weights decay over time
+- Scar tissue: corrections leave permanent repair markers, penalize future retrieval
+- Kintsugi: golden seams on corrected memories (visible in dashboard)
+- Consolidation engine: merge similar memories, strengthen edges, expire scars
+- Danger theory: feedback signals from user messages (surprise, contradiction, resolution)
+- LLM judge: rates memory usefulness at session end
+- Multi-domain support with domain isolation
+- 19-page real-time dashboard (FastAPI + Chart.js + D3.js)
+
+**Phase 3 — Forest**
+- Morphogenetic self-calibration: adaptive sigmoid response curves per parameter
+- System states: FLOW / STRESS / CURIOSITY state machine with parameter multipliers
+- Contextual bandits: Thompson sampling for retrieval strategy selection
+- Dreaming: slow-wave consolidation + REM recombination at session end
+- Apoptosis: controlled pruning of low-vitality memories with fragment salvage
+- Niche construction: Louvain clustering for domain reorganization proposals
+- Cascade detector: Extended Kalman Filter for system health prediction
+- Dimensional folding: operational regime detection (BOOTSTRAP → LEARNING → MATURE)
+- Maintenance scheduler: tiered (intra-session, daily, weekly, monthly) background maintenance
+- Self-model: organism health metrics, parameter drift detection
+- MCP server with auto-session management and dashboard co-launch
+- CLI (`fractal`) with store, retrieve, inspect, export, health, maintenance commands
+
+### Security
+- SQL injection protection via parameterized queries throughout
+- Input validation on all public API boundaries
+- Domain name sanitization (alphanumeric + hyphens/underscores/dots only)

fractal_memory-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing to Fractal Memory
+
+## Development Setup
+
+```bash
+# Clone
+git clone https://github.com/entropyvector/fractal-memory.git
+cd fractal-memory
+
+# Create virtual environment
+python3.11 -m venv .venv
+source .venv/bin/activate
+
+# Install with all extras
+pip install -e ".[dev,dashboard]"
+```
+
+## Running Tests
+
+```bash
+pytest
+```
+
+Tests use `pytest-asyncio` with `asyncio_mode = "auto"` — async test functions are detected automatically.
+
+## Code Style
+
+- **Async-first** — all I/O must be async. No sync database drivers in async contexts.
+- **Type annotations** on all public functions.
+- **No hardcoding** — all configurable parameters go in `FractalConfig` (`src/fractal_memory/config.py`).
+- **Extend, don't rewrite** — no phase may rewrite prior phase code. Use hooks, callbacks, or new modules.
+- **Single source of truth** — `FractalConfig` is the only config object. No shadow configs.
+
+See `internal/requirements/CODE_REQUIREMENTS.md` for the full specification.
+
+## Project Structure
+
+```
+src/fractal_memory/
+├── __init__.py          # FractalMemory main class
+├── config.py            # FractalConfig — all parameters
+├── storage.py           # SQLite persistence (async via aiosqlite)
+├── models.py            # Data models (Memory, Session, etc.)
+├── cli.py               # Click CLI (fractal command)
+├── mcp/
+│   └── server.py        # MCP server (fractal-memory-mcp)
+└── dashboard/           # FastAPI dashboard
+    ├── app.py
+    ├── templates/
+    └── static/
+```
+
+## Architecture
+
+The codebase is organized by evolutionary phases. Each phase builds on the previous:
+
+- **Phase 1 (Pioneer):** Core store/retrieve, 5 zoom levels, lifecycle, gate
+- **Phase 2 (Shrub):** Association network, danger theory, scar tissue, consolidation
+- **Phase 3 (Forest):** Morphogenetic fields, niche construction, dreaming, maintenance
+- **Phase 4 (Old Growth):** Aliveness diagnostic, memory packs, cross-domain (planned)
+
+See `internal/plans/` for detailed phase plans.
+
+## Pull Request Process
+
+1. Fork the repository
+2. Create a feature branch from `main`
+3. Make your changes (follow the code style above)
+4. Add tests for new functionality
+5. Run `pytest` and ensure all tests pass
+6. Submit a PR against `main`
+
+## Reporting Issues
+
+Open an issue at https://github.com/entropyvector/fractal-memory/issues with:
+- What you expected to happen
+- What actually happened
+- Steps to reproduce
+- Your Python version and OS

fractal_memory-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Zaur Jafarov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.