friday-memory 1.2.0__tar.gz

friday_memory-1.2.0/.env.example

@@ -0,0 +1,25 @@
+# ==============================================================================
+# Friday — Self-Hosted Configuration
+# ==============================================================================
+
+# 1. Friday Server Security (Set your own secret password to protect your server)
+FRIDAY_API_KEY=choose_any_secret_password_you_want
+
+# 2. LLM for Autonomous Graph Extraction (Extracts nodes & edges from memories)
+# Get a key at: https://platform.deepseek.com (~$0.14/M tokens)
+DEEPSEEK_API_KEY=sk-your_deepseek_api_key_here
+DEEPSEEK_BASE_URL=https://api.deepseek.com
+DEEPSEEK_MODEL=deepseek-chat
+
+# 3. Semantic Memory Layer (Mem0)
+# Get a free key at: https://mem0.ai
+MEM0_API_KEY=m0-your_mem0_api_key_here
+
+# 4. Knowledge Graph Database (Neo4j - bundled in docker-compose)
+NEO4J_URI=bolt://neo4j:7687
+NEO4J_USER=neo4j
+NEO4J_PASSWORD=choose_a_strong_password_here
+
+# 5. Server Options
+HOST=0.0.0.0
+PORT=8000

friday_memory-1.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,57 @@
+name: Bug Report
+description: Create a report to help us improve Friday
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report! Please provide as much context as possible.
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of what the bug is.
+      placeholder: Describe the unexpected behavior...
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Step-by-step instructions to reproduce the issue.
+      value: |
+        1. Start Friday via 'docker compose up -d'
+        2. Execute MCP query with '...'
+        3. See error
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What should happen under normal conditions.
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Environment Logs & Traceback
+      description: Paste any relevant terminal logs, Docker container output, or traceback.
+      render: shell
+  - type: dropdown
+    id: deployment
+    attributes:
+      label: Deployment Environment
+      options:
+        - Docker Compose (Localhost)
+        - Docker Compose (Cloud / EC2 / VPS)
+        - Native Python / Local Virtualenv
+        - Other
+    validations:
+      required: true
+  - type: input
+    id: client
+    attributes:
+      label: AI Coding Client
+      description: Cursor, Claude Code CLI, Antigravity, VS Code, Windsurf, etc.
+      placeholder: e.g. Cursor 0.44 / Claude Code 1.0

friday_memory-1.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,35 @@
+name: Feature Request
+description: Suggest an idea or enhancement for Friday
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        We welcome architectural proposals, new MCP tools, and integration ideas!
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: Is your feature request related to a problem or limitation?
+      placeholder: I encounter friction when trying to...
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed Solution / Architecture
+      description: Describe the solution you'd like to see implemented.
+      placeholder: Friday should provide an endpoint / tool that...
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Any alternative solutions or workarounds you have considered.
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      options:
+        - label: I am willing to submit a pull request implementing this feature

friday_memory-1.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,43 @@
+## Description
+
+Brief summary of the changes introduced in this pull request and the rationale behind them.
+
+Fixes #(issue)
+
+## Type of Change
+
+- [ ] `fix`: Bug fix (non-breaking change which fixes an issue)
+- [ ] `feat`: New feature (non-breaking change which adds functionality)
+- [ ] `refactor`: Code refactoring or architectural cleanup
+- [ ] `perf`: Performance improvement
+- [ ] `docs`: Documentation updates or corrections
+- [ ] `chore`: CI, dependency, or tooling updates
+
+## Architecture Impact
+
+- [ ] Updates MCP tool schema (`mcp/server.py`)
+- [ ] Modifies database layer (SQLite / Neo4j / ChromaDB)
+- [ ] Modifies Neural Studio visualizer (`studio/`)
+- [ ] None (internal logic / tests only)
+
+## Verification & Testing
+
+Explain how the changes were verified:
+
+```bash
+# Example test run
+make test
+make lint
+```
+
+- [ ] Unit tests added / updated and passing green
+- [ ] Smoke tested locally with FastAPI TestClient
+- [ ] Verified live against Docker Compose stack (if applicable)
+- [ ] No regression in token extraction or graph ingestion
+
+## Checklist
+
+- [ ] Code follows project style guidelines (`ruff check .`)
+- [ ] All public methods and endpoints have clear docstrings
+- [ ] Relevant documentation updated (README, API reference, or docs)
+- [ ] Commit message follows Conventional Commits format

friday_memory-1.2.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: Friday CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test & Quality Checks
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Install Dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install ruff
+
+      - name: Run Test Suite
+        run: python -m pytest tests/ -v --tb=short
+
+      - name: Code Style & Quality Check
+        run: ruff check .

friday_memory-1.2.0/.github/workflows/publish.yml

@@ -0,0 +1,76 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution packages
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Store distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/friday-memory
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+
+  attach-to-release:
+    name: Attach assets to GitHub Release
+    needs: [build]
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Upload artifacts to Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*

friday_memory-1.2.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+.env
+.env.local
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+# Runtime data (never commit these)
+facts/
+vector_db/
+exports/
+logs/
+conversations/
+projects/
+blueprints/*.md
+integrations/*.md
+
+# Editor
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Docker volumes
+neo4j_data/
+neo4j_logs/

friday_memory-1.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,18 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+We pledge to make participation in our project a harassment-free experience for everyone.
+
+## Our Standards
+✅ Be respectful and constructive  
+✅ Welcome newcomers  
+✅ Focus on what is best for the community  
+❌ No harassment, insults, or personal attacks  
+❌ No discriminatory language  
+
+## Enforcement
+Violations may be reported to the project maintainers.  
+We will review and respond to all complaints.
+
+---
+Adapted from [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

friday_memory-1.2.0/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to Friday
+
+Thank you for your interest in contributing to Friday. We welcome bug reports, architectural improvements, new integrations, and documentation updates.
+
+## Development Setup
+
+### Prerequisites
+- Python 3.11+
+- Docker and Docker Compose
+- Git
+
+### Quick Start
+```bash
+git clone https://github.com/friday-memory/friday.git
+cd friday
+cp .env.example .env
+
+# Install dependencies
+make install
+# or: pip install -r requirements.txt
+
+# Run test suite
+make test
+# or: python -m pytest tests/ -v
+```
+
+## Contribution Workflow
+
+1. **Fork the Repository**: Create your fork on GitHub.
+2. **Create a Feature Branch**:
+   ```bash
+   git checkout -b feat/your-feature-name
+   ```
+3. **Write Tests**: Add test coverage under `tests/` for any new functionality or bug fixes.
+4. **Verify Standards**:
+   ```bash
+   make test
+   make lint
+   ```
+5. **Commit Changes**: Use [Conventional Commits](https://www.conventionalcommits.org/):
+   - `feat:` New features or tools
+   - `fix:` Bug fixes
+   - `docs:` Documentation updates
+   - `refactor:` Code restructuring without behavior changes
+   - `perf:` Performance improvements
+   - `chore:` Dependency or CI updates
+6. **Open a Pull Request**: Submit your PR with a completed checklist from the PR template.
+
+## Architectural Conventions
+
+- **State Persistence**: Memory layers must remain modular:
+  - Facts Ledger: Strict deterministic ground truths.
+  - Episodic Memory: Semantic vector embeddings.
+  - Graph Topology: Relational entity relationships.
+- **Protocol Compliance**: Tool schemas must adhere strictly to the Model Context Protocol (MCP) standard.
+- **Performance**: Operations in the hot path of MCP tool execution should maintain sub-100ms response latencies where possible.
+
+## Questions & Discussions
+
+For technical discussions, feature proposals, and architectural questions, visit [GitHub Discussions](https://github.com/friday-memory/friday/discussions).

friday_memory-1.2.0/Dockerfile

@@ -0,0 +1,34 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for layer caching
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY gateway/ ./gateway/
+COPY layers/ ./layers/
+COPY pipelines/ ./pipelines/
+COPY orchestrator/ ./orchestrator/
+COPY mcp/ ./mcp/
+COPY studio/ ./studio/
+
+# Create runtime directories
+RUN mkdir -p /app/facts /app/vector_db /app/logs /app/blueprints /app/seed
+
+# Copy seed data
+COPY seed/ ./seed/
+
+EXPOSE 8000 8001
+
+HEALTHCHECK --interval=30s --timeout=10s --start-period=20s --retries=3 \
+  CMD curl -f http://localhost:8000/health || exit 1
+
+CMD ["uvicorn", "gateway.main:app", "--host", "0.0.0.0", "--port", "8000", "--log-level", "info"]

friday_memory-1.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Friday Contributors
+
+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.

friday_memory-1.2.0/Makefile

@@ -0,0 +1,33 @@
+.PHONY: help install dev test lint format docker-up docker-down docker-logs clean
+
+help: ## Show this help message
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-16s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install Python dependencies
+	pip install -r requirements.txt
+
+dev: ## Run local development server
+	uvicorn gateway.main:app --host 0.0.0.0 --port 8000 --reload
+
+test: ## Run test suite
+	python -m pytest tests/ -v --tb=short
+
+lint: ## Check code formatting and linting
+	ruff check .
+
+format: ## Auto-format code with ruff
+	ruff format .
+
+docker-up: ## Launch Friday and Neo4j via Docker Compose
+	docker compose up -d
+
+docker-down: ## Stop Docker Compose containers
+	docker compose down
+
+docker-logs: ## View container logs
+	docker compose logs -f
+
+clean: ## Clean Python caches and temporary files
+	find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete 2>/dev/null || true
+	rm -rf .pytest_cache .ruff_cache 2>/dev/null || true