weftgate

New session. Same project brain.

Local memory and context for coding agents, with verification built in.

Keep the decisions your next coding session needs. Weftgate gives connected agents a shared local notebook, compact source pointers and handoffs with observed checks. Use it throughout the task: understand, remember, build, verify and resume.

One install, one MCP server, one local memory store. Mnemo’s everyday local memory workflow is built in. Connect each client to the same repository to share saved notes; no second project is needed.

No API key. No runtime dependencies. Local storage. No automatic transcript capture. Context, recall and default verification make no network calls. Explicitly enabled test commands run your repository's code and can have their own side effects.

Watch the 36-second memory workflow · Try the copyable example · Creator demo kit

Try it

pip install weftgate
cd /path/to/your/repo
weftgate setup --agents codex,claude,cursor,antigravity --hooks --instructions
weftgate brief "your next task"   # relevant notes + current source pointers
weftgate memory stats             # your local notebook and freshness counts
weftgate doctor                   # inspect coverage and configured integrations

From source: pip install git+https://github.com/Avinash-Amudala/weftgate.git. For development, bash scripts/bootstrap.sh installs the extras and runs the offline self-test.

Start with the session-memory example: save a decision, retrieve it in a new process, observe a test in a handoff, then change the source and watch stale notes disappear from default recall. It takes no AI account. The short film illustrates those executed CLI steps; it is not an editor recording.

Related MCP server: opzyai

From first brief to the next session

weftgate brief "order retries" --reference app/orders.py --budget 1200
weftgate remember "Order idempotency" "Keep duplicate requests idempotent." --file app/orders.py
# Your coding agent makes the change. Then:
weftgate check app/orders.py
weftgate handoff "Order retries" "Added retry handling. Next: review timeout behavior." --file app/orders.py --run --require-ready
# In Codex, Claude Code, Cursor or another MCP client:
weftgate brief "order retries"

Use paths and routes that exist in your project. Configure the commands the last step should observe in weftgate.toml:

[weftgate.workflow]
commands = ["python -m pytest -q"]

--run explicitly permits execution of configured, allowlisted commands. A checkpoint distinguishes proven failures, review findings, missing test evidence and changes during verification. --require-ready exits 3 when evidence is incomplete. A ready checkpoint covers those contracts and commands only. Workflow details.

Context responses contain source pointers, not file bodies. The default budget is 1,500 estimated tokens with a hard cap of 6,000 UTF-8 JSON bytes. Actual model token counts vary. weftgate ledger reports payload bytes and gate events; it does not invent a savings percentage or equate every rejection with an avoided retry. Context coverage and budgets.

Memory that notices changed code

Weftgate's notebook checks explicit file, environment, route, import and symbol claims before saving them. A proven false claim is refused with available suggestions. Uncertain claims stay available for review. Recall checks original source hashes, and notes with changed or missing evidence stay hidden by default. Source anchors support a claim about freshness; the note's prose remains unverified.

weftgate remember "Database access" "Use the declared connection." --env DATABASE_URL
weftgate recall "database"
weftgate recall "database" --include-stale
weftgate memory stats

handoff saves a summary and its scoped checkpoint in the same notebook. Another agent can resume through brief; remembered test evidence is labeled historical and changes to the current tree are detected. Obvious secret patterns are scrubbed from note text, but do not treat this as permission to store credentials.

Already have Mnemo data? Preview and import selected memories without installing Mnemo or modifying its database:

weftgate memory import /path/to/mnemo.sqlite --limit 10
weftgate memory import /path/to/mnemo.sqlite --limit 10 --apply

The legacy repository remains compatible for existing transcript and team-hub users. Automatic capture, external embeddings and team federation are outside the public local workflow. They are not silently enabled by migration. Memory and trust · Migration and backup · Architecture and scope.

Use it with your agent

weftgate setup --agents all --hooks --instructions --dry-run
weftgate setup --agents codex,claude,cursor,antigravity --hooks --instructions

The standard-library MCP server requires no extra package. Example MCP configuration:

{"mcpServers": {"weftgate": {"command": "weftgate", "args": ["mcp"]}}}

Run the server with the repository as its working directory. weftgate setup --agents all writes supported project configs and prints snippets for clients with global settings. CLI and MCP use the same functions. Start with brief, save decisions with remember, and use handoff for the next session. Focused context, recall, checkpoints, memory transfer and the existing verification tools remain available.

Client versions, project trust and organization policy affect hook activation. MCP tools and rules alone do not force an agent to use the gate. Local hooks are guardrails; require the GitHub Action in branch protection to enforce merge checks. Integration paths, activation checks and official references.

Verification throughout the workflow

Check proposed edits, changed files, a working tree or a pull request. Hooks and CI use the same gate as the CLI and MCP tools. The original gate fixture shows:

The demo uses an intentionally broken fixture, not a field benchmark:

REJECT  import 'requestz'       → did you mean requests?
REJECT  env var 'DATABSE_URL'   → did you mean DATABASE_URL?
REJECT  handler 'helth'         → did you mean health?

Fix the three names and the fixture passes. A computed key such as os.environ[key] returns review, because static analysis cannot establish its value. To reproduce: weftgate eval mutate --fixture --seed 13.

The rule is block only on a positive, machine-checkable falsehood. Suggestions accompany findings when a nearby candidate exists. An accept verdict is not a test suite result or proof that the application works; inspect coverage with weftgate doctor.

Supported verification contracts

This is an early static analyzer with bounded parsers. It does not execute your app, replace tests or a security scanner, or cover every framework. Python, Node, and monorepo import resolution can depend on runtime configuration. Missing or ambiguous evidence must soften; please report a false block with a minimal reproduction. Historical field runs document methods and limitations, rather than a claim of zero false positives.

CLI and CI

git diff | weftgate check -
weftgate check --staged
weftgate check --path app/main.py --content proposed.py
weftgate claim '[{"kind":"route","method":"POST","path":"/users"}]'
weftgate audit --format=json
weftgate index --show routes

Exit codes: 0 allows the change, 1 blocks according to policy, 2 means a usage or configuration error. Use --format=github for workflow annotations.

name: Verify connections
on: [pull_request]
permissions:
  contents: read
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0
      - uses: Avinash-Amudala/weftgate@v0.3.0
        with:
          mode: check             # or audit to inspect the repository

The Action supports base, paths (shell-quoted paths, no shell expansion), block-on, and python-version. Use a full checkout for diff ancestry. The pre-commit hooks use the same gate; pin rev: v0.3.0.

Configure the contract

# weftgate.toml
[weftgate]
oracles = ["env_vars", "imports_lockfile", "routes_fastapi"]
block_on = "reject"                 # reject | review | never
env_declared_in = [".env.example"]

Precedence: WEFTGATE_* environment variables, repository configuration, user configuration, then defaults. The index lives in the user cache, outside the repo. weftgate doctor explains the selected configuration and missing contracts.

Outcome claims such as “tests passed” need machine-checkable evidence. Re-running a named test command or probing a URL requires explicit --run and the configured allowlist. See security and execution boundaries.

Contribute

If this helps your workflow, star the repository so you can find it again. To help shape the tool, share which agent you used, whether the first brief was useful, and what you had to explain again in Discussions.

bash scripts/bootstrap.sh
.venv/bin/ruff check .
.venv/bin/ruff format --check .
.venv/bin/mypy weftgate
.venv/bin/python -m weftgate.selftest
.venv/bin/python -m pytest -q --cov=weftgate --cov-fail-under=85

Start with CONTRIBUTING.md, the oracle guide, and AGENTS.md. New oracles need a real broken example, a correct example, and a dynamic case that reviews. Reproducible false blocks and missing-contract reports are especially useful.

Apache-2.0 · Changelog · Launch plan