memforge-ai 0.1.55__tar.gz

memforge_ai-0.1.55/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "memforge",
+  "interface": {
+    "displayName": "MemForge"
+  },
+  "plugins": [
+    {
+      "name": "memory",
+      "source": {
+        "source": "local",
+        "path": "./integrations/codex/memforge-memory"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

memforge_ai-0.1.55/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "memforge",
+  "description": "MemForge plugin marketplace for agent memory integrations.",
+  "owner": {
+    "name": "MemForge Team"
+  },
+  "plugins": [
+    {
+      "name": "memory",
+      "description": "MemForge hook and MCP memory integration for Claude Code.",
+      "source": "./integrations/claude-code/memforge-memory",
+      "category": "productivity"
+    }
+  ]
+}

memforge_ai-0.1.55/.dockerignore

@@ -0,0 +1,19 @@
+.git
+.github
+.pytest_cache
+.ruff_cache
+.venv
+.env
+.memforge
+__pycache__
+*.py[cod]
+*.sqlite
+*.db
+*.log
+
+admin-ui/.tmp-test
+admin-ui/dist
+admin-ui/node_modules
+
+docs/.vitepress/cache
+docs/.vitepress/dist

memforge_ai-0.1.55/.env.example

@@ -0,0 +1,33 @@
+# Runtime storage
+# Docker Compose overrides MEMFORGE_BASE_DIR to /data inside the API container.
+MEMFORGE_BASE_DIR=.memforge
+MEMFORGE_ADMIN_API_PORT=8765
+MEMFORGE_CORS_ORIGINS=http://localhost:5174
+
+# LLM enrichment
+MEMFORGE_ENRICHMENT_MODEL=claude-sonnet-4-20250514
+MEMFORGE_ENRICHMENT_BASE_URL=https://api.anthropic.com
+MEMFORGE_ENRICHMENT_API_KEY=
+
+# Embeddings
+MEMFORGE_EMBEDDING_MODEL=text-embedding-3-small
+MEMFORGE_EMBEDDING_BASE_URL=https://api.openai.com/v1
+MEMFORGE_EMBEDDING_API_KEY=
+
+# Optional Docker Hub mirror prefix for restricted networks.
+# Example: MEMFORGE_DOCKERHUB_PREFIX=docker.m.daocloud.io/library/
+MEMFORGE_DOCKERHUB_PREFIX=
+MEMFORGE_DEBIAN_MIRROR=
+MEMFORGE_DEBIAN_SECURITY_MIRROR=
+MEMFORGE_PYPI_INDEX_URL=
+MEMFORGE_NPM_REGISTRY=
+
+# Optional host ports when 8765 or 5174 are already in use. The authentication-
+# free OSS beta always publishes them on 127.0.0.1; shared deployment is unsupported.
+MEMFORGE_API_HOST_PORT=8765
+MEMFORGE_ADMIN_UI_HOST_PORT=5174
+
+# Agent adapter overrides
+MEMFORGE_API_URL=http://127.0.0.1:8765
+MEMFORGE_API_TOKEN=
+MEMFORGE_AGENT_QUEUE_DB=

memforge_ai-0.1.55/.env.mirrors.example

@@ -0,0 +1,15 @@
+# Build mirrors for restricted or slow registry networks.
+# Use directly with:
+# docker compose --env-file .env.mirrors.example up --build
+#
+# Or copy to .env if you also want to edit local model/API settings:
+# cp .env.mirrors.example .env
+
+MEMFORGE_DOCKERHUB_PREFIX=docker.m.daocloud.io/library/
+MEMFORGE_DEBIAN_MIRROR=https://mirrors.tuna.tsinghua.edu.cn/debian
+MEMFORGE_DEBIAN_SECURITY_MIRROR=https://mirrors.tuna.tsinghua.edu.cn/debian-security
+MEMFORGE_PYPI_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
+MEMFORGE_NPM_REGISTRY=https://registry.npmmirror.com
+
+MEMFORGE_API_HOST_PORT=8765
+MEMFORGE_ADMIN_UI_HOST_PORT=5174

memforge_ai-0.1.55/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,29 @@
+name: Bug report
+description: Report a reproducible problem in MemForge
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What happened?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Include commands, payload shape, and relevant logs with secrets removed.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version or commit
+      placeholder: 0.1.0 or commit SHA
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      placeholder: Python, Node, OS, database/vector settings

memforge_ai-0.1.55/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,24 @@
+name: Feature request
+description: Suggest an improvement for MemForge
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What workflow is hard today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: What would a clean solution look like?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any simpler options or trade-offs?

memforge_ai-0.1.55/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## Summary
+
+## Verification
+
+- [ ] `make lint`
+- [ ] `make test`
+- [ ] `make ui-lint`
+- [ ] `make ui-test`
+- [ ] `make ui-build`
+
+## Notes
+
+- [ ] Docs updated when behavior or setup changed
+- [ ] No local data, private URLs, credentials, or generated caches included

memforge_ai-0.1.55/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  python:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --extra dev
+      - run: uv build
+      - run: uv run python scripts/verify_release_artifacts.py dist
+      - run: uv run python scripts/sync_plugin_mcp_proxy.py --check
+      - run: uv run ruff check src tests scripts/sync_plugin_mcp_proxy.py
+      - run: uv run pytest -q -n 4 --dist worksteal --durations=25 --durations-min=0.2
+
+  admin-ui:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: admin-ui
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24.15.0"
+          cache: npm
+          cache-dependency-path: admin-ui/package-lock.json
+      - run: npm ci
+      - run: npm run lint
+      - run: npm test
+      - run: npm run build

memforge_ai-0.1.55/.github/workflows/publish-pypi.yml

@@ -0,0 +1,44 @@
+name: Publish Python distribution
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheel and source distribution
+        run: uv build
+      - name: Verify distribution metadata and release tag
+        run: >-
+          python scripts/verify_release_artifacts.py dist
+          --release-tag "${{ github.event.release.tag_name }}"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/memforge-ai
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+      - name: Publish to PyPI with Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

memforge_ai-0.1.55/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Virtual environments
+.venv/
+venv/
+
+# Node / Vite
+node_modules/
+admin-ui/node_modules/
+admin-ui/dist/
+admin-ui/.tmp-test/
+
+# Local runtime data and repository workspace configuration
+data/
+*.db
+*.db-wal
+*.db-shm
+*.sqlite
+*.sqlite-wal
+*.sqlite-shm
+.memforge/
+
+# Local agent/editor config
+docs/local/
+.codex/
+.claude/
+.superpowers/
+.agents/
+!.agents/
+!.agents/plugins/
+!.agents/plugins/marketplace.json
+.mcp.json
+.mcp.local.json
+AGENTS.local.md
+CLAUDE.local.md
+
+# Environment and secrets
+.env
+.env.*
+!.env.example
+!.env.*.example
+*.pem
+*.key
+
+# OS / IDE
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.swo

memforge_ai-0.1.55/.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace

memforge_ai-0.1.55/AGENTS.md

@@ -0,0 +1,73 @@
+# AGENTS.md — Project conventions for Codex
+
+## Code Quality
+
+- Code should look like "first-place design", not "bug-fix archaeology." Comments, docstrings, and prompts should read as if the current approach was always the intended design. A new developer reading the code shouldn't see refactoring history.
+- Prefer clean, robust ownership boundaries over fallback workarounds. Do not add DB-only fallback paths for lifecycle operations that also require search/vector cleanup; route those operations through the owning service instead.
+- Do not introduce batching, reduce a batch size, or split a schema merely to bypass a provider limit or failing path. First identify whether the limit exposes a better schema, transport, ownership, or execution-boundary design; present the alternatives and tradeoffs to the user and obtain explicit confirmation before choosing batching as the remediation.
+- When batching is explicitly approved or is already part of the workload contract, keep it a transport/computation detail: it must not create additional business or lifecycle states, weaken complete coverage, or change atomic and fail-closed correctness semantics.
+
+## Project
+
+- See `README.md` for setup and project orientation.
+- See `docs/architecture.md` for the full system design.
+- See `docs/design/agent-session-saas-plugin-flow.md` for the Codex and Claude Code adapter flow.
+
+## Plugin Release Validation
+
+- Test MemForge plugin changes through the same remote plugin install/update path that users use. Do not hand-edit files under `~/.codex/plugins/cache`, and do not add a manual MCP server entry as a workaround.
+- For pre-release validation, publish or install a dev/RC plugin artifact from the remote GitHub marketplace source (`shno-labs/mem-forge`), such as `0.1.17-rc.1`, then promote the same commit/tag to the final release after validation.
+- When cutting an MCP plugin version, commit the version bump and integration copies first, push the branch, then create a remote tag that names the plugin version, for example `memforge-memory-v0.1.21-rc.4`. Point Codex at that tag with `codex plugin marketplace add https://github.com/shno-labs/mem-forge.git --ref <tag>` and install with `codex plugin add memory@memforge`.
+- After installing, verify `codex plugin list --json --marketplace memforge --available`, `codex mcp list`, the marketplace checkout commit/tag, and the cache directory under `~/.codex/plugins/cache/memforge/memory/<version>`. Restart Codex and repeat the version and MCP cwd checks; a restart must not fall back to an older cache.
+- Keep the long-lived Claude Code `memforge` marketplace on the unpinned GitHub source `shno-labs/mem-forge` with auto-update enabled. Its user-level source in `~/.claude/settings.json` and `~/.claude/plugins/known_marketplaces.json` must not contain `ref`; otherwise each marketplace refresh remains locked to that branch or tag and cannot discover later plugin versions.
+- Run Claude Code RC, branch, or release-tag installation tests under a disposable `CLAUDE_CONFIG_DIR` (or an equivalently isolated validation profile), never against the long-lived user configuration. Perform the marketplace add/install/update and restart checks inside that isolated profile, discard it after validation, and verify before release closure that the normal user marketplace still has no `ref`. Do not copy the isolated marketplace registry or plugin cache back into `~/.claude`.
+- Keep Codex and Claude Code on the same remote plugin source. Neither client should reference `/Users/i551096/Dev/mem-inception` as a marketplace or plugin source, because local path installs hide packaging and cache drift.
+- If Codex Desktop still falls back after a restart, check for workspace plugin sources such as `.agents/plugins/marketplace.json` in saved workspace roots. A local checkout can silently reinstall `memory@memforge` from its own `integrations/codex/memforge-memory` tree even when the configured marketplace points at the remote tag.
+- Release gates for plugin changes should include unit tests, lint, package/install parity, MCP `initialize` and `tools/list` version/tool checks after restart, SessionStart and Stop/PreCompact hook smoke tests, and at least one harmless read/write MCP smoke in a test workspace when write tools change.
+
+## Refactor/Deploy Goal Workflow
+
+- Before starting a goal-scoped refactor, pull `main` first in every affected repo, then create a fresh `codex/` branch or isolated worktree from the updated main. Do not keep implementing on an older feature branch just because it is convenient.
+- Before starting any PR merge, check the affected repo for existing open PRs and local/remote `codex/` branches that might be stale, superseded, or still awaiting action. Report the findings and explicitly call out whether any branch or PR should be handled before the merge.
+- Treat the approved design and implementation plan as the completion contract. Audit the current implementation against every design requirement before claiming the design is fully covered.
+- Record every user-approved deferred MemForge feature or optimization as one GitHub Issue in the coordinating repository. The issue must state the problem and evidence, affected repositories, execution trigger, acceptance criteria, explicit non-goals, type/area, `status:candidate` or `status:ready`, and `priority:P0` through `priority:P3`. Do not treat chat, handoff notes, ADR asides, or duplicate cross-repo issues as the execution backlog, and do not prescribe an unreviewed implementation as settled design.
+- When a validated change materially corrects or clarifies the design, update the repo-owned `docs/adr` record in the same goal/PR. Persist the durable decision and consequences, not the debugging chronology.
+- Use online research when making design or technical judgment calls, especially for retrieval, ranking, database search, GraphRAG, deployment, security, or API-contract decisions. Prefer primary sources and current official docs; when useful, inspect relevant open-source project designs or code for implementation insight before settling the approach.
+- When explaining or refining retrieval behavior, lead with the runtime flow: user query, independent retrieval channels, fusion/ranking, and exact source/time/visibility predicates. Distinguish vector search, content BM25, metadata lexical channels, graph expansion, and deterministic source/time listing.
+- Run review incrementally while implementing. When the user asks for two reviewers, use exactly two independent reviewer lanes: one Claude Code reviewer and one Codex reviewer. Do not defer review until a large final diff.
+- Reviewer feedback is evidence to evaluate. For each finding, decide whether it is valid for the design/runtime contract, whether the proposed fix is proportionate, and whether it should be implemented, rejected, or deferred; record that decision in a handoff log outside the repo.
+- Continue the review/fix loop until both reviewers and the implementer approve the result, with no accepted blocker left open.
+- For cloud-impacting changes, CF deploy and detailed smoke testing are required before the goal can be considered complete. Record the deployment target, smoke commands or UI/API steps, and redacted evidence in the handoff log.
+- Open PRs for every repo with committed changes. The goal is not complete until the relevant PRs exist, verification evidence is recorded, and no required repo is left with uncommitted goal work.
+
+## OSS Self-Hosted Release Validation
+
+- Validate self-hosted releases through the documented newcomer path: a clean Docker Compose project, loopback-only ports unless explicitly testing exposure, the default SQLite-backed data volume, Admin UI/API startup, first-run model configuration, a representative source sync, memory retrieval, and the packaged local MCP path.
+- Use an isolated Compose project and dedicated volume for smoke tests. Never reuse or delete a developer's existing MemForge volume, source data, plugin cache, or external service state merely to obtain a clean result.
+- Prove SQLite persistence by restarting the API or Compose stack against the same isolated data volume and rechecking sources, documents, memories, keyword/vector health, and MCP retrieval.
+- Treat source support as an execution matrix, not a registry count. For each registered source type, state whether server collection, local-agent collection, managed intake, credentials, browser sessions, VPN/internal reachability, or an external provider is required. Classify each type as verified, unsupported by design, blocked by a missing prerequisite, or failed.
+- Exercise local-agent sources through the real server-issued job and daemon path. A direct package injection may diagnose the service boundary, but it does not prove that the documented daemon workflow works.
+- For public-beta readiness, separately assess newcomer reproducibility, first-run UX, error messages, documentation accuracy, default data/privacy boundaries, and obvious exposure or secret-handling footguns. Give a conservative `GO`, `CONDITIONAL GO`, or `NO-GO`, with the smallest required fixes or disclosure language.
+- Do not present fixture-backed LLM/provider behavior as production-provider validation. Record the fixture contract, then distinguish it from real connector credentials and model-provider coverage.
+
+## Lifecycle Canary Convergence
+
+- Before another retry or canary, review the complete design contract and static call path for the affected state transition: transaction ownership, operation ordering, idempotency, stale guards, retry semantics, and SQLite/Cloud adapter parity.
+- Define a falsifiable hypothesis and the exact confirming or rejecting evidence before changing code or data. Classify historical data, migration residue, and one-off provider/runtime failures separately from reproducible shared-contract violations.
+- Prefer one bounded joint snapshot that correlates durable runs/jobs, Lifecycle Plans and mutations, current and stale Support, Source Projection lineage, Reviews/Findings, vector outbox, and process health. Do not replace it with repeated narrow probes that guess at adjacent causes.
+- Use a bounded convergence sequence: one report-only inventory, one exact dry-run, one controlled apply when authorized, and one strict incremental audit. Stop when the incremental audit is clean and no relevant state changed.
+- Never fabricate Evidence, infer missing provenance from semantic similarity, or silently rewrite lifecycle history to make an audit pass. Preserve historical Plans, Relations, Reviews, Findings, and failed jobs.
+- Report current and historical populations separately. Distinguish active Memories from superseded or retired lifecycle records and classify unexpected growth by lifecycle reason and bounded time cohort.
+
+## Architecture Decision Ownership
+
+- Record shared Memory lifecycle, retrieval, and storage-contract decisions in an OSS `docs/adr` record as the canonical design source. This includes transaction boundaries and work/outbox semantics that every storage adapter must implement.
+- Do not duplicate shared semantics in a Cloud ADR. Update a Cloud ADR only for a material HANA, Cloud Foundry, or other cloud-only consequence; link the canonical OSS ADR and describe only how Cloud implements or constrains that shared contract.
+
+## OSS and Cloud Contract Consistency
+
+- Treat OSS storage/service protocols as the source of truth for shared behavior. Cloud adapters must implement the same method names, signatures, visibility semantics, filters, pagination, transaction/work semantics, and error behavior unless a documented cloud-only route applies.
+- Keep caller identity and visibility explicit in contracts, including `include_private`, `owner_user_id`, `AccessScope`, source/status/project filters, limit, and offset.
+- Test shared behavior at the boundary users hit: route/service input, generated store query or adapter call, and returned count/list/detail semantics. A method-existence assertion alone is not contract coverage.
+- For shared routes and services, keep adapter-level contract coverage that proves SQLite/OSS and Cloud interpret the contract consistently. Test fixtures and fake stores must implement current protocol signatures; a permissive or narrower fake is contract drift.
+- Do not add source-type special cases, compatibility bridges, or route-level fallbacks to hide adapter drift. Update the shared protocol and each adapter implementation directly.

memforge_ai-0.1.55/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 - Unreleased
+
+- Initial public repository preparation.
+- Self-hosted MemForge service with FastAPI admin API, SQLite persistence,
+  FTS search, Chroma vector search, and MCP tools.
+- React admin UI for memories, entities, sources, review, and settings.
+- Codex and Claude Code integration packages with thin hook adapters and
+  service-owned agent-session package generation.
+- Jira browser-session capture now runs in the client CLI and uploads to the
+  server over POST /api/auth/jira-session; the server no longer scrapes a
+  browser. New `memforge adapter auth jira watch` keeps the session fresh
+  proactively. PAT mode is unchanged.

memforge_ai-0.1.55/CLAUDE.md

@@ -0,0 +1,11 @@
+# CLAUDE.md — Project conventions for Claude Code
+
+## Code Quality
+
+- Code should look like "first-place design", not "bug-fix archaeology." Comments, docstrings, and prompts should read as if the current approach was always the intended design. A new developer reading the code shouldn't see refactoring history.
+
+## Project
+
+- See `README.md` for setup and project orientation.
+- See `docs/architecture.md` for the full system design.
+- See `docs/design/agent-session-saas-plugin-flow.md` for the Codex and Claude Code adapter flow.

memforge_ai-0.1.55/CODE_OF_CONDUCT.md

@@ -0,0 +1,23 @@
+# Code Of Conduct
+
+MemForge should be a useful place to build and discuss agent memory systems.
+Be direct, kind, and technical. Assume good intent, but do not excuse behavior
+that makes collaboration harder for others.
+
+Expected behavior:
+
+- welcome newcomers and answer questions with patience
+- critique ideas and code, not people
+- keep discussions relevant to the project
+- respect private data and do not ask people to share secrets or proprietary
+  transcripts
+
+Unacceptable behavior:
+
+- harassment, personal attacks, or discriminatory language
+- publishing another person's private information
+- repeatedly derailing issues or pull requests
+- knowingly submitting credentials, malware, or private data
+
+Maintainers may edit, hide, or remove comments and contributions that violate
+this code of conduct.

memforge_ai-0.1.55/CONTEXT.md

@@ -0,0 +1,106 @@
+# Domain Context
+
+## Workspace selection
+
+- **Workspace Directory** — The principal-scoped list of workspaces the caller may know about, including current active/selectable state. Listing it is discovery, not a prerequisite for data-plane requests.
+- **Requested Workspace** — An explicit `workspace_id` supplied on one HTTP or MCP operation. It is validated without revealing inaccessible workspaces.
+- **Local Workspace Binding** — A user-confirmed client-side mapping from a Git repository or ordinary directory to a workspace. It supplies a request selector without sending the local path or granting authority.
+- **Hook Workspace Fallback** — An optional client-local workspace used only by automatic hooks when no project binding or pinned session selection exists. It never scopes an interactive operation.
+- **Authorized Workspace Context** — The single workspace selected, authorized, and bound to one data-plane request. Handlers and durable work consume this context rather than resolving workspace again.
+- **Workspace Selection Source** — The reason the Authorized Workspace Context was chosen: Requested Workspace or the caller's singleton accessible workspace.
+- **Repository Context** — Repository attribution used for provenance and retrieval relevance. It never selects or authorizes a workspace.
+
+## Source synchronization
+
+- **Source Lifecycle** — Whether a configured source is active or paused. Lifecycle is independent of where collection executes and whether the current device can perform that collection.
+- **Local Execution** — Collection work that must run through the source owner's MemForge daemon on a user-controlled device.
+- **Device Readiness** — Whether the source owner's local daemon is recently connected and able to accept collection work.
+- **Connection Readiness** — Whether a source-specific connection dependency, such as an authenticated browser session, is usable or requires user action.
+- **Local Source Readiness** — The user-facing result derived from Device Readiness and Connection Readiness for a source that uses Local Execution. It never replaces Source Lifecycle.
+- **Source Readiness** — The compact source-row outcome derived from execution location, Device Readiness when collection is local, and Connection Readiness when the connector exposes it.
+- **Source Sync Activity** — The user-visible lifecycle of current or recent work to bring one source up to date. It can cover both collection from the source and processing into memories.
+- **Collection** — Reading source items and, when required, transferring them from the execution device to MemForge.
+- **Collection Manifest** — An attempt-scoped declaration of stable Source Item identities and opaque revisions. It describes discovered membership without carrying every item body.
+- **Collection Coverage** — The proof attached to one collection result: a Complete Snapshot covers the whole configured scope, a Bounded Delta covers only explicit changes since a checkpoint, and Partial coverage proves neither absence nor a safe checkpoint advance.
+- **Candidate Checkpoint** — A provider position proposed by collection but not made current until the corresponding Source Projection and lifecycle transaction succeeds.
+- **Processing** — Turning collected source items into stored documents and memories.
+- **Attachment Inventory** — The current provider entities owned by a source item, whether or not the item's current body references or displays them. Inventory membership alone does not make an attachment current Source Evidence.
+- **Body Artifact Reference** — An authoritative reference from one exact current source-body revision to a provider Artifact. It preserves the provider's reference semantics rather than inferring reachability from filenames, URLs, or attachment ownership.
+- **Effective Source Artifact** — A current provider Artifact reached through a resolved Body Artifact Reference and pinned to its exact provider identity and revision. Only Effective Source Artifacts enter current materialization, Source Projection, and derivation.
+- **Artifact Membership Coverage** — Whether every Artifact-producing construct in one current source-body revision was resolved against authoritative provider inventory. Only Complete coverage makes an omitted prior Artifact an authoritative removal.
+- **Progress Snapshot** — The latest trustworthy statement of an activity's phase and measurable progress. It is a current observation, not a history of progress events.
+- **Determinate Progress** — Progress with a trustworthy total, presented as completed out of total.
+- **Indeterminate Progress** — Progress whose total is not yet knowable, presented without a percentage while still reporting useful counts when available.
+
+## Memory provenance
+
+- **Memory Origin Kind** — The derived category describing how one provenance source introduced knowledge into MemForge: **Direct User** for an explicit user lifecycle action, **Managed Capture** for a system-managed coding-agent capture, or **Configured Source** for a user-configured ingestion connection. It does not replace Source Type, Client, Repository Context, ownership, or visibility.
+- **Direct User** — Knowledge explicitly confirmed through a user lifecycle action such as creating or correcting a Memory. The submitting coding agent is the Client, and an associated repository is Repository Context; neither becomes the Source.
+- **Managed Capture** — Knowledge produced from a system-created capture Source, such as an Agent Session Source, without requiring the user to configure an ingestion connection.
+- **Configured Source** — Knowledge produced from a user-configured ingestion connection such as Confluence, Jira, Teams, GitHub Repository, or Local Repository.
+
+## Memory retrieval
+
+- **Requested Retrieval Intent** — An optional query-scoped hint selected by an Agent Client from the user's conversational goal. It may request General Hybrid Retrieval, Known Item Lookup, or Relationship Exploration, but cannot weaken visibility, provenance, or facet constraints.
+- **Resolved Retrieval Intent** — The validated query-scoped purpose that selects ranked retrieval behavior from the user's goal rather than from the query language or an individual retrieval mechanism. The service resolves General Hybrid Retrieval, Known Item Lookup, or Relationship Exploration from a valid Requested Retrieval Intent or a deterministic fallback.
+- **General Hybrid Retrieval** — Ranked retrieval for an open-ended natural-language query, including when the query and relevant Memory use different languages. Semantic, content lexical, metadata lexical, and relationship evidence remain independent contributors rather than mutually exclusive modes. Avoid: _Semantic lookup, lexical lookup_.
+- **Known Item Lookup** — Ranked retrieval for a specifically named or identified item, such as an external identifier, title, or code symbol. An Agent Client keeps the query self-contained and quotes an exact title or name when conversation context supplies one; the service may use that explicit identity for bounded metadata recall while preserving the full query for the other channels. It expresses the user's expected target, not a lexical-only implementation.
+- **Relationship Exploration** — Ranked retrieval whose primary goal is to discover Memories connected through entities or relationships. It does not bypass normal visibility or provenance constraints.
+- **Deterministic Listing** — A separate current-state enumeration constrained by an explicit time window and optional Source facets, without relevance ranking or an invented query. It is not a Resolved Retrieval Intent. Avoid: _Empty search, queryless semantic search_.
+
+## Memory lifecycle migration
+
+- **Lifecycle Migration Inventory** — A backend scan of every active Configured Source in the datastore, without applying a caller's source-discoverability filter. Agent Session sources are candidates when the Lifecycle Gate is not Enabled or the bidirectional Active Same-Source Support Invariant is violated in either direction. Inventory output contains identifiers and counts, never private source content or owner identity.
+- **Active Same-Source Support Invariant** — Support authority and its source provenance projection are bidirectionally complete for active configured-source Memories: every `memory_sources` edge has active same-source Support, and every active Support has the exact `memory_sources` edge for its Evidence document. An Enabled gate does not override either violation.
+- **Support Provenance Projection** — The `memory_sources` read model used by source facets, source-card counts, timestamps, access filtering, and document provenance. It materializes exact active Support membership but is not lifecycle authority; a cross-document Relation without Support does not create this projection.
+- **Lifecycle Migration Attempt** — One idempotent durable recovery job identified by an explicit attempt label. Unprovable lineage remains a durable open finding and keeps destructive lifecycle gated; semantic similarity cannot close it.
+- **Non-Migrating SQLite Open** — An existing SQLite workspace opened through `Database.connect(run_migrations=False)`. It uses SQLite read-only/query-only mode, does not create the database or parent directories, and does not create schema or run migrations. It is for operator evaluation, never normal serving or repair.
+
+## Memory review
+
+- **Review** — An auditable request for a human-authorized decision when MemForge cannot safely complete or classify a Memory change on its own. Review status records whether that request is pending or terminal; it is not a Memory lifecycle state.
+- **Review Decision** — One action allowed by a Review's kind and presentation, together with its exact lifecycle postcondition. The same approve or reject storage result can represent different user-facing decisions only when the presentation states those consequences explicitly.
+- **Decision Fingerprint** — A deterministic digest of the Review identity, pinned participants, and proposed decision input. A caller must present the current fingerprint when applying a decision so analysis of an older Review cannot mutate newer state.
+- **Decision Manifest** — A bounded, caller-supplied set of Review Decisions and Decision Fingerprints proposed for validation or confirmed application. It is request data, not a durable workflow, lifecycle state, or all-or-nothing transaction.
+- **Cross-Source Conflict Review** — A Review of a proposed contradiction between two independently supported active Memories. Confirming or dismissing the finding closes the Review but does not select source authority or retire either Memory.
+
+## Connector authentication
+
+- **Teams Access Token** — A short-lived bearer credential that authorizes one local Teams collection session against a specific Teams service audience.
+- **Teams Browser Session** — A persistent, user-authenticated Teams Web session that can acquire fresh Teams Access Tokens without another visible sign-in while enterprise SSO remains valid.
+- **Silent Session Renewal** — Renewal of a Teams Access Token through the Teams Browser Session without presenting authentication UI to the user.
+- **Interactive Reauthentication** — A visible Teams Web sign-in required when the Teams Browser Session can no longer renew silently because enterprise SSO, MFA, or access policy requires user interaction.
+
+## Source organization
+
+**Project**:
+A semantic relevance grouping for memories and their sources inside a workspace. A Project is not a personal list organization mechanism or an access boundary.
+_Avoid_: Collection, folder, source group
+
+**Source**:
+A configured connection that contributes source items and memories to a workspace.
+_Avoid_: Integration instance, connector row
+
+**Source List View**:
+A user's presentation of Sources in one workspace. It may filter, sort, or prioritize Sources without changing their configuration or Project binding.
+_Avoid_: Collection
+
+**Pinned Source**:
+A Source prioritized for one user within its existing Project group. Pinning neither moves nor duplicates the Source and has no effect on other users.
+_Avoid_: Favorite collection, promoted source
+
+**Source List Sort**:
+A user's ordering preference applied independently inside each Project group after Pinned Sources have been prioritized.
+_Avoid_: Source priority
+
+**Source Search**:
+An ephemeral narrowing of the Source List View by Source name, source type, or Project. Searching does not change persisted Source organization.
+_Avoid_: Source query
+
+## GitHub Repository scope
+
+- **Repository Access** — Where GitHub API access executes. `cloud_pull` uses MemForge Cloud credentials and network access; `local_push` uses the source owner's daemon, local `gh` session, VPN, and network access. It never changes the data origin: both modes read the configured remote GitHub repository. Avoid: _Local clone mode, local repository_.
+- **Repository Base Scope** — The positive boundary of a GitHub Repository source. An empty `include_paths` list means the whole repository; otherwise only the selected remote folders and files are candidates. Avoid: _Local folder selection_.
+- **Repository Exclusion** — A selected remote folder or file removed from the Repository Base Scope. Exclusions win over inclusions and apply to all descendants. A child below an excluded path cannot be re-included. Avoid: _Ignore hint, inferred outdated content_.
+- **Effective Repository Scope** — The deterministic set of remote files remaining after base scope, exclusions, and extension filters are applied. Suggested exclusions require explicit user confirmation and never change this set automatically.
+- **Repository File Identity** — Built-in GitHub Repository collection identifies a file by canonical repository path because Git has no immutable file ID. A path move is a removed file plus a new file unless a future/provider adapter supplies explicit authoritative rename evidence; matching blob SHA alone never proves a move because copy plus delete is ambiguous.