a-memory 1.7.0__py3-none-any.whl

.ai-memory.toml

@@ -0,0 +1,21 @@
+project_name = ""
+scan_dirs = [
+  "src", "lib", "app", "models", "controllers", "services",
+  "db", "migrations", "schema", "core", "extended", "features",
+  "graph", "hooks", "lifecycle", "rag", "shared", "wiki",
+  "adapters", "agent_core", "ariel", "delegation", "memory",
+  "modules", "reflex_flags", "skills", "tools", "cognitive",
+  "tests", "scripts", "config",
+]
+extensions = [
+  ".py", ".js", ".ts", ".tsx", ".jsx", ".rb", ".go", ".rs",
+  ".java", ".cs", ".c", ".cpp", ".h", ".hpp", ".sql", ".yaml",
+  ".yml", ".json", ".toml", ".proto", ".graphql",
+]
+ignore_patterns = [
+  "node_modules", "venv", ".git", "__pycache__", ".idea",
+  "dist", "build", "target", "vendor", ".pytest_cache",
+  "*.min.js", "*.min.css", "*.map", ".ai-memory", ".codegraph",
+]
+output_format = "markdown"
+max_context_tokens = 4000

.claude/CLAUDE.md

@@ -0,0 +1,109 @@
+# CLAUDE.md
+
+<!-- Add your custom instructions below. Repowise will never modify anything outside the REPOWISE markers. -->
+<!-- Examples: coding style rules, test commands, workflow preferences, constraints -->
+
+<!-- REPOWISE:START — Do not edit below this line. Auto-generated by Repowise. -->
+## IMPORTANT: Codebase Intelligence Instructions for mcp-ariel-memory
+
+> This repository is indexed by [Repowise](https://repowise.dev).
+> Use the MCP tools below for orientation, discovery, and enriched context
+> (documentation, ownership, history, decisions). **Always verify against
+> actual source files before making changes** — the index may be stale.
+
+Last indexed: 2026-08-08 (commit e428650)
+### Entry Points
+- `__main__.py`
+- `mcp_server/server.py`
+### Tech Stack
+**Languages:** Python
+**Frameworks:** Pydantic
+
+**Infra:** Docker, Docker Compose### Architectural Layers
+| Layer | Files | Purpose |
+|-------|-------|---------|
+| Application | 72 |  |
+| Service | 5 |  |
+| Config | 19 |  |
+| Utility | 22 |  |
+| Docs & Tooling | 43 |  |
+| Test | 56 |  |
+
+### Guided Tour (12 steps)
+1. `README.md`
+2. `server.py`
+3. `__main__.py`
+4. `index.js`
+5. `connection.py`
+6. `config.py`
+... and 6 more steps
+### Hotspots (High Churn)
+| File | Churn | 90d Commits | Owner |
+|------|-------|-------------|-------|
+| `rag/engine.py` | 99.3th %ile | 35 | Ariel Memory |
+| `tests/test_mcp/test_tools_e2e.py` | 98.6th %ile | 10 | Ariel Memory |
+| `tests/test_hypothesis.py` | 97.8th %ile | 10 | Ariel Memory |
+| `mcp_server/tools_layer.py` | 97.1th %ile | 26 | Ariel Memory |
+| `shared/saga.py` | 96.4th %ile | 23 | Ariel Memory |
+
+## Code health
+Three signals: **defect risk** (the overall score), **maintainability** (smells that hurt readability/change-cost without predicting bugs), and **performance** (static performance RISK: I/O-in-loop / N+1 shapes that waste work, high-precision/low-recall). Maintainability and performance are co-equal views, never blended into the defect headline. See `docs/CODE_HEALTH.md`.
+
+Defect risk, Hotspot health: 4.09/10 (stable) ·
+Average: 6.82/10 ·
+Worst: 1.0/10 (`shared/saga.py`)
+Maintainability, Average: 8.89/10
+Performance risk, Average: 9.85/10
+
+### Critical biomarkers
+- `tests/test_rag_scoring.py` — churn risk — impact −2.4
+- `tests/test_integration.py` — churn risk — impact −2.4
+- `features/audit_trail.py` — untested hotspot — impact −2.0
+- `features/rate_limiting.py` — untested hotspot — impact −2.0
+- `graph/temporal.py` — untested hotspot — impact −2.0
+
+### Repowise MCP Tools
+
+This repo has the Repowise MCP server configured. The tools below answer questions `grep`/`Read` cannot. Every response carries an `_meta` envelope with `index_age_days`, `indexed_commit`, and a `stale_warning` only when the index has actually diverged from HEAD — silence means the index is current.
+
+**When to call which tool:**
+
+| Tool | What only this tool answers |
+|------|------------------------------|
+| `get_answer(question)` | Synthesised answer with citations and a content-grounded `confidence`. First call for "how does X work" / "where is Y" / "why is Z". Value questions may return `grounding: "extracted"` — the verbatim source line, no synthesis involved. On low confidence returns `best_guesses` with one-line justifications. |
+| `get_context(targets=[...])` | Triage card for files/modules/symbols — title, summary, signatures, `hotspot` bit, `decision_records` titles, `symbol_id`s. File targets auto-upgrade to a `verified` skeleton (every signature, ~37% of a full Read). `include=["callers"]` works on file targets too (import + call rollup). |
+| `get_symbol(...)` | Source bytes with live-verified bounds. Three forms: `"path.py::Name"` (indexed symbol), `"path.py:140-180"` (live range read, ≤200 lines), `"repowise#<hex>"` (omission ref). Index misses return `fallback_lines` from a live grep instead of a dead end. |
+| `search_codebase(query, mode?, kind?, symbol_kind?)` | Hybrid code search. `mode="auto"` (default) routes by query shape: an identifier → indexed symbol hits (`symbol_id`/`file`/line bounds — pipe into `get_symbol`), a path → file pages (pipe into `get_context`), prose → wiki-semantic search, mixed → hybrid (symbols first). Force a branch with `mode=symbol\|path\|concept\|hybrid`. Concept hits carry `search_method` (`embedding` vs `bm25` fallback); decision records rank below file pages unless the query is why-shaped. |
+| `get_why(query, targets?)` | Architectural decision archaeology — *why* the code is shaped this way. Call before refactors or pattern divergences. Falls back to git archaeology when no ADRs exist for a file. |
+| `get_risk(targets, changed_files?)` | What history says about touching these files: churn, owners, blast radius. Pass `changed_files` for PR mode → returns a `directive` (`will_break`, `missing_cochanges`, `missing_tests`). |
+| `get_health(targets?, include?)` | Code-health scores + biomarker findings (defect / maintainability / performance pillars). Self-check before a PR — read the same signals the merge-gate judges your change on. Default is lean; opt in with `include`: `["accuracy"]` (does the score rank the buggy files first — precision@K + `lift`), `["signals"]` (per-file prior-defects / churn / owners / degree, targeted mode), `["churn_complexity"]` (volatile-and-complex danger-zone files), `["biomarkers"]` (all findings), and a dimension name `["performance"]` / `["defect"]` / `["maintainability"]` to filter findings to one pillar. |
+| `get_dead_code(...)` | Tiered unreachable / unused-export / zombie-package findings. Run before a cleanup sprint, not before a targeted fix. |
+| `get_overview(repo?)` | Architecture map + `tool_guide` recipes. One-time orientation; skip on subsequent calls in the same session. |
+
+**Trust protocol — when a response replaces reading the source:**
+- `verified: true` on any response means the served content was checked against the live working tree. **Never follow a verified response with a Read of the same lines** — you would be paying twice for identical bytes.
+- `get_answer` with `confidence: "high"` or `grounding: "extracted"` is content-grounded (asserted values were verified against retrieved source; ≥1 citation is source-backed). Cite it directly. `quotes` entries `{path, lines, quote}` are verbatim live source — quote them instead of re-reading.
+- Reading code: `get_context` skeleton first (~37% of a full Read), then `get_symbol` for bodies, `"path.py:a-b"` range reads for anything between symbols. Raw `Read` is for files the index marks `mostly_full` or cannot serve.
+- The **only** re-read triggers: `bounds: "approximate"`, `_meta.stale_warning`, `search_method: "bm25"`, or `confidence: "low"`/`retrieval_quality: "weak"`.
+- Disallowed rationalizations for extra reads: "just to be safe", "to double-check the tool", "to see the full context" (use the skeleton / a range read), "the file might have changed" (that is what `verified` already checked).
+
+**Composition tips:**
+- `get_answer` → if `confidence` is `medium`/`low`, follow `best_guesses[0].file` or `fallback_targets[0]` into `get_context`, then `get_symbol` for bytes.
+- `get_context` returns `decision_records` titles → `get_why(targets=[...])` for the rationale; `hotspot: true` → `get_risk` before editing.
+- PR review → `get_risk(targets=[...], changed_files=[...])`; read the `directive` block first.
+- A `tombstone` error means the file was deleted/renamed since indexing — follow `successor_paths`.
+
+### Output Distillation
+
+- Prefer `repowise distill <cmd>` for noisy commands — test runs, builds, `git status`/`log`/`diff`, searches, file listings. It runs the command unchanged (exit code preserved) and prints a compact, errors-first rendering; every error line survives.
+- Output may contain a marker like `[repowise#a1b2c3d4e5f6: 230 lines omitted (~6.1k tokens); restore: repowise expand a1b2c3d4e5f6]`. The omitted content is fully preserved — run `repowise expand <ref>` to retrieve it, or `repowise expand <ref> -q <regex>` for just the matching lines.
+- Never re-run a command to see omitted output; expand the marker instead.
+- For structure-level questions about a large indexed file ("what's in here", "which function handles X"), `get_context(["path"], include=["skeleton"])` returns the file with bodies elided — every signature plus the bodies of the most central symbols — at a fraction of the cost of a full Read.
+
+### Codebase Conventions
+**Commands:**
+- Test: `pytest`
+- Lint: `ruff check .`
+- Typecheck: `mypy .`
+
+<!-- REPOWISE:END -->

.codegraph/.gitignore

@@ -0,0 +1,5 @@
+# CodeGraph data files — local to each machine, not for committing.
+# Ignore everything in .codegraph/ except this file itself, so transient
+# files (the database, daemon.pid, sockets, logs) never show up in git.
+*
+!.gitignore

.coderabbit.yaml

@@ -0,0 +1,43 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+language: "en-US"
+
+reviews:
+  profile: "chill"
+  request_changes_workflow: false
+  high_level_summary: true
+  poem: false
+  review_status: true
+  collapse_walkthrough: false
+  auto_review:
+    enabled: true
+    drafts: false
+  path_instructions:
+    - path: "mcp_server/**/*.py"
+      instructions: |
+        Review MCP server code. Focus on:
+        - Async correctness (no blocking calls in async functions)
+        - Error handling (no bare except)
+        - Type annotations on public functions
+        - SQL injection prevention (parameterized queries only)
+    - path: "shared/**/*.py"
+      instructions: |
+        Review shared modules. Focus on:
+        - Thread safety (no shared mutable state without locks)
+        - Connection management (proper cleanup, no leaks)
+        - Cryptographic operations (correct nonce handling)
+    - path: "tests/**/*.py"
+      instructions: |
+        Review test code. Focus on:
+        - Test isolation (no shared state between tests)
+        - Async test correctness
+        - No hardcoded paths or credentials
+        - Property-based tests should have proper shrink strategies
+    - path: "rag/**/*.py"
+      instructions: |
+        Review RAG engine. Focus on:
+        - FTS5 query safety (no user input in SQL)
+        - Binary search correctness (hamming distance math)
+        - Search result ranking consistency
+
+chat:
+  auto_reply: true

.dockerignore

@@ -0,0 +1,19 @@
+__pycache__
+*.pyc
+*.pyo
+.git
+.gitignore
+*.md
+!README.md
+!README_EN.md
+tests/
+docs/
+*.db
+*.json
+!pyproject.toml
+.mcp-ariel-memory/
+.ai-memory/
+.codegraph/
+.cursorrules
+.windsurfrules
+.github/

.gitattributes

@@ -0,0 +1,22 @@
+* text=auto
+
+*.py text eol=lf
+*.js text eol=lf
+*.ts text eol=lf
+*.tsx text eol=lf
+*.json text eol=lf
+*.md text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf
+*.sh text eol=lf
+*.txt text eol=lf
+*.toml text eol=lf
+*.sql text eol=lf
+
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.sqlite binary
+*.db binary
+*.pyc binary

.github/CODEOWNERS

@@ -0,0 +1,11 @@
+# Default owner for everything in the repo
+* @Cipher208
+
+# Python source
+*.py @Cipher208
+
+# MCP server
+mcp_server/ @Cipher208
+
+# CI/CD
+.github/ @Cipher208

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,109 @@
+name: Bug Report
+description: Report a bug to help us improve
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug! Please fill out the form below.
+
+  - type: input
+    id: version
+    attributes:
+      label: mcp-ariel-memory version
+      description: "Output of `pip show mcp-ariel-memory | grep Version`"
+      placeholder: "1.0.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: python
+    attributes:
+      label: Python version
+      options:
+        - "3.10"
+        - "3.11"
+        - "3.12"
+        - "3.13"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - Linux
+        - macOS
+        - Windows
+        - Docker
+    validations:
+      required: true
+
+  - type: dropdown
+    id: transport
+    attributes:
+      label: Transport
+      options:
+        - stdio
+        - HTTP (Streamable)
+        - Docker
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug description
+      description: A clear description of what the bug is
+      placeholder: "Describe the bug..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: Minimal steps to reproduce the behavior
+      placeholder: |
+        1. Start server with...
+        2. Send request...
+        3. See error...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What you expected to happen
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What actually happened
+    validations:
+      required: true
+
+  - type: textarea
+    id: config
+    attributes:
+      label: Configuration
+      description: "Relevant config.yaml or environment variables (redact secrets)"
+      render: yaml
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs
+      description: "Paste relevant log output (run with `--log-level DEBUG`)"
+      render: shell
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Any other context about the problem

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Documentation
+    url: https://cipher208.github.io/a-memory/
+    about: Check the documentation before opening an issue
+  - name: Discussions
+    url: https://github.com/Cipher208/a-memory/discussions
+    about: Ask questions and discuss ideas

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,54 @@
+name: Feature Request
+description: Suggest a new feature or enhancement
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature! Please describe what you'd like.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: "What problem does this feature solve? Is it related to a frustration?"
+      placeholder: "I'm always frustrated when..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: Describe the solution you'd like
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any alternative solutions or features you've considered
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Memory (L1-L4)
+        - RAG / Search
+        - Wiki
+        - Knowledge Graphs
+        - Hooks / Lifecycle
+        - Authentication / Security
+        - MCP Tools
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Any other context, mockups, or examples

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## Summary
+
+<!-- What does this PR do? Why is it needed? -->
+
+## Changes
+
+<!-- Bullet list of key changes -->
+
+## Checklist
+
+- [ ] Tests pass locally (`pytest tests/ -v`)
+- [ ] Lint passes (`ruff check .`)
+- [ ] New code has tests
+- [ ] Documentation updated (if applicable)
+- [ ] No breaking changes (or documented in summary)
+
+## Related Issues
+
+<!-- Closes #123 -->

.github/codeql-config.yml

@@ -0,0 +1,14 @@
+# CodeQL configuration to silence non-Python warnings
+paths-ignore:
+  - 'npm/**'
+  - 'venv/**'
+  - 'node_modules/**'
+  - 'htmlcov/**'
+  - 'strix_runs/**'
+  - 'graphify-out/**'
+  - '**/*.js'
+  - '**/*.ts'
+  - '**/*.c'
+  - '**/*.cpp'
+  - '**/*.h'
+  - '**/*.so'

.github/coderabbit.yaml

@@ -0,0 +1,7 @@
+reviews:
+  auto_review:
+    enabled: false
+  request_changes_workflow: true
+  base_branches:
+    - master
+    - main

.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "chore"

.github/labeler.yml

@@ -0,0 +1,25 @@
+labels:
+  - label: "bug"
+    paths:
+      - "**/*.py"
+    title:
+      - regex: "\\bfix(es|ed)?\\b"
+      - regex: "\\bbug\\b"
+
+  - label: "dependencies"
+    paths:
+      - "pyproject.toml"
+      - "requirements*.txt"
+
+  - label: "ci"
+    paths:
+      - ".github/**"
+
+  - label: "documentation"
+    paths:
+      - "**/*.md"
+      - "docs/**"
+
+  - label: "tests"
+    paths:
+      - "tests/**"

.github/release-drafter.yml

@@ -0,0 +1,81 @@
+name-template: 'v$RESOLVED_VERSION'
+tag-template: 'v$RESOLVED_VERSION'
+template: |
+  ## Changes
+
+  $CHANGES
+
+  ## Contributors
+
+  $CONTRIBUTORS
+
+categories:
+  - title: '🚀 Features'
+    labels:
+      - 'feature'
+      - 'enhancement'
+  - title: '🐛 Bug Fixes'
+    labels:
+      - 'fix'
+      - 'bugfix'
+      - 'bug'
+  - title: '🧰 Maintenance'
+    labels:
+      - 'chore'
+      - 'dependencies'
+      - 'refactor'
+  - title: '📚 Documentation'
+    labels:
+      - 'documentation'
+      - 'docs'
+  - title: '🧪 Testing'
+    labels:
+      - 'test'
+      - 'testing'
+  - title: '🔒 Security'
+    labels:
+      - 'security'
+
+change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
+change-title-escapes: '\<*_&'
+version-resolver:
+  major:
+    labels:
+      - 'major'
+  minor:
+    labels:
+      - 'minor'
+      - 'feature'
+      - 'enhancement'
+  patch:
+    labels:
+      - 'patch'
+      - 'fix'
+      - 'bugfix'
+      - 'bug'
+      - 'chore'
+      - 'dependencies'
+      - 'documentation'
+      - 'test'
+      - 'security'
+  default: patch
+autolabeler:
+  - label: 'feature'
+    title:
+      - '/^feat/i'
+  - label: 'fix'
+    title:
+      - '/^fix/i'
+  - label: 'chore'
+    title:
+      - '/^chore/i'
+      - '/^refactor/i'
+  - label: 'documentation'
+    title:
+      - '/^docs/i'
+  - label: 'test'
+    title:
+      - '/^test/i'
+  - label: 'security'
+    title:
+      - '/^security/i'

.github/release.yml

@@ -0,0 +1,22 @@
+changelog:
+  exclude:
+    labels:
+      - ignore-for-release
+    authors:
+      - dependabot[bot]
+  categories:
+    - title: "Breaking Changes"
+      labels:
+        - breaking-change
+    - title: "New Features"
+      labels:
+        - enhancement
+    - title: "Bug Fixes"
+      labels:
+        - bug
+    - title: "Dependencies"
+      labels:
+        - dependencies
+    - title: "Other Changes"
+      labels:
+        - "*"

.github/workflows/auto-label.yml

@@ -0,0 +1,20 @@
+name: Auto Label
+
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened]
+
+env:
+  ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION: true
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/labeler@v5
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/auto-merge-dependabot.yml

@@ -0,0 +1,28 @@
+name: Auto Merge Dependabot
+
+on: pull_request
+
+env:
+  ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION: true
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  auto-merge:
+    if: github.actor == 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fetch Dependabot metadata
+        id: metadata
+        uses: dependabot/fetch-metadata@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Auto-merge minor and patch updates
+        if: steps.metadata.outputs.update-type != 'version-update:semver-major'
+        run: gh pr merge --auto --squash "$PR_URL"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}