recallgate 0.1.0__tar.gz

recallgate-0.1.0/LICENSE

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

recallgate-0.1.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: recallgate
+Version: 0.1.0
+Summary: Token-efficient controllable memory gate for AI coding agents.
+Author: RecallGate Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/lamguo/recallgate
+Project-URL: Repository, https://github.com/lamguo/recallgate
+Project-URL: Issues, https://github.com/lamguo/recallgate/issues
+Keywords: ai,agent,memory,token,context,cli,coding-agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/dependencies-0-%234ADE80?style=flat-square">
+    <img alt="RecallGate" src="https://img.shields.io/badge/dependencies-0-%234ADE80?style=flat-square">
+  </picture>
+  <img src="https://img.shields.io/badge/API%20calls-0-%2394a3b8?style=flat-square" alt="0 API calls">
+  <img src="https://img.shields.io/badge/license-MIT-%2394a3b8?style=flat-square" alt="MIT">
+  <img src="https://img.shields.io/badge/tests-31%20passing-%234ADE80?style=flat-square" alt="Tests">
+</p>
+
+# RecallGate
+
+> **Give every AI agent only the memory it needs — and nothing else.**
+
+RecallGate is a **token-efficient, controllable memory gate for AI coding agents**.
+
+It helps Claude Code, Codex CLI, Cursor, Gemini CLI, Copilot-style agents, and multi-agent coding workflows stop wasting context on irrelevant history.
+
+```text
+Without RecallGate:  1,240 tokens → $0.02 per ask → model reads everything
+With RecallGate:        95 tokens → $0.001 per ask → model reads only what matters
+                                                                  ▲ 92.3% cheaper
+```
+
+**Zero dependencies. Zero API calls. Offline. One `.recallgate` folder.**
+
+---
+
+## Install
+
+```bash
+pip install recallgate
+# or from source
+git clone https://github.com/lamguo/recallgate.git
+cd recallgate && pip install -e .
+```
+
+## Quick start — 10 seconds to value
+
+```bash
+# 1. Init a workspace in your project
+cd my-project && recall-gate init
+
+# 2. Add project rules (they stay in Git-friendly .md files)
+recall-gate add "Keep zero core dependencies." --role coder --priority high
+recall-gate add "Tests use temp fixtures, not example files." --role tester
+recall-gate add "README must match CLI behavior exactly." --role writer
+
+# 3. Generate a 100-token brief for your coding agent
+recall-gate brief "fix CI pipeline test failure" --role tester --budget 100
+```
+
+Paste the output into your AI agent. That's it.
+
+---
+
+## Why you'll use this
+
+### "My AI keeps forgetting the project rules"
+
+```bash
+recall-gate correct "model keeps suggesting requests library — we use stdlib only"
+```
+
+Outputs a <100-token correction brief. Paste it into any AI agent. Problem solved.
+
+### "I'm burning tokens on irrelevant context"
+
+```bash
+recall-gate estimate --task "fix tests" --role tester --json
+```
+
+Returns structured data: `{"full_active_memory_tokens": 1240, "injected_brief_tokens": 95, "estimated_saving_percent": 92.3}`. Know your savings before you inject.
+
+### "Coder, tester, and writer agents need different context"
+
+```bash
+recall-gate brief "fix deployment" --role coder     # sees deployment rules
+recall-gate brief "update docs"   --role writer     # sees README guidelines
+recall-gate brief "review PR"     --role reviewer    # sees audit checklist
+```
+
+Each agent role sees only its relevant memories. Shared rules go to `--role all`.
+
+### "I have 50 memories and don't know what's stale"
+
+```bash
+recall-gate review --apply          # auto-archive low-value memories
+recall-gate list --sort use_count   # see what's never been used
+recall-gate search "fixtures"       # find without opening index.json
+```
+
+---
+
+## Features
+
+| | What | Why it matters |
+|---|---|---|
+| 🎯 | **Role-filtered briefs** | Coder gets coding rules, writer gets docs rules, tester gets test rules |
+| ✂️ | **Token budget control** | Set `default_budget = 100` in config — briefs are hard-capped |
+| 🔄 | **Memory lifecycle** | `active` → `archive` → `trash` → `delete`. Nothing lost by accident |
+| 🔧 | **Edit in place** | `recall-gate edit mem_0001 --priority critical` — no delete+re-create |
+| 🔍 | **Full-text search** | Searches content, short text, keywords, scope, type, priority |
+| 📦 | **JSON output** | `--json` on every command — pipe into scripts, editors, MCP |
+| 📂 | **Git-friendly storage** | Each memory is a `.md` file with YAML frontmatter. Diff, commit, review |
+| 🌐 | **CJK support** | Chinese memory gets readable slugs and meaningful keywords |
+| 🧼 | **Auto-review** | `recall-gate review --apply` archives unused memories automatically |
+
+### Memory lifecycle
+
+```text
+active   → readable by default
+archive  → hidden but recoverable
+trash    → blocked from agents, still recoverable
+deleted  → permanently removed from index and disk
+```
+
+### Role-based routing
+
+Every memory targets one or more roles. `--role all` means everyone sees it.
+
+```bash
+recall-gate brief "fix tests"    --role tester     # only tester memories
+recall-gate brief "update README" --role writer    # only writer memories
+recall-gate brief "review"       --role reviewer   # only reviewer memories
+```
+
+The goal: **Shared outline, private depth.**
+
+---
+
+## Command reference
+
+```
+recall-gate
+  init                           Create workspace
+  add <content>                  Add a memory
+  edit/update <id>               Edit memory fields
+  info <id>                      Full memory details
+  list [--sort] [--reverse]      List memories
+  search <query>                 Full-text search
+  brief <task>                   Token-efficient memory brief
+  correct <issue>                Correction brief (model forgets)
+  estimate                       Token cost estimate
+  review [--apply]               Suggest/apply cleanup
+  archive / trash / restore      Lifecycle commands
+  promote <id>                   Move conversation to project
+  delete <id> --yes              Permanent removal
+
+Global flags:
+  --json      Machine-readable output on all commands
+  --root      Target a specific workspace (for automation)
+```
+
+---
+
+## About injection
+
+`brief` prints plain text by design in v0.1.0. You copy the output into Claude Code, Codex CLI, Cursor, Gemini CLI, Copilot Chat, or any other coding agent.
+
+Automatic injection is intentionally not included in the first version because the core tool should stay local, predictable, and provider-agnostic. Future integrations can add MCP, editor plugins, or agent hooks on top of the same brief engine.
+
+---
+
+## Design philosophy
+
+```text
+Default model calls:       0
+Default API keys:          0
+Default runtime deps:      0
+Default storage:           local Markdown + JSON
+Default tokenizer:         built-in estimator
+Default test discovery:    python -m unittest discover
+```
+
+RecallGate is built to be **cheap, local, and predictable**. No vector database. No LLM calls. No network. No vendor lock-in. You commit your `.recallgate` folder to Git, and every teammate gets the same memory.
+
+### What RecallGate is
+
+- A local memory gate
+- A memory firewall
+- A token-saving brief generator
+- A role-based memory router
+- A stale model memory correction layer
+
+### What RecallGate is not
+
+- Not a hosted memory service
+- Not a vector database
+- Not a full AI agent framework
+- Not a replacement for Claude Code, Codex, Cursor, or Copilot
+- Not a tool that blindly remembers everything
+
+---
+
+## Status
+
+`v0.1.0` — alpha MVP with **31 unit tests, 0 dependencies, and 17 CLI commands**.
+
+**Coming next:** MCP server, editor plugins, auto-conflict detection, and optional AI compression.
+
+## License
+
+MIT

recallgate-0.1.0/README.md

@@ -0,0 +1,204 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/dependencies-0-%234ADE80?style=flat-square">
+    <img alt="RecallGate" src="https://img.shields.io/badge/dependencies-0-%234ADE80?style=flat-square">
+  </picture>
+  <img src="https://img.shields.io/badge/API%20calls-0-%2394a3b8?style=flat-square" alt="0 API calls">
+  <img src="https://img.shields.io/badge/license-MIT-%2394a3b8?style=flat-square" alt="MIT">
+  <img src="https://img.shields.io/badge/tests-31%20passing-%234ADE80?style=flat-square" alt="Tests">
+</p>
+
+# RecallGate
+
+> **Give every AI agent only the memory it needs — and nothing else.**
+
+RecallGate is a **token-efficient, controllable memory gate for AI coding agents**.
+
+It helps Claude Code, Codex CLI, Cursor, Gemini CLI, Copilot-style agents, and multi-agent coding workflows stop wasting context on irrelevant history.
+
+```text
+Without RecallGate:  1,240 tokens → $0.02 per ask → model reads everything
+With RecallGate:        95 tokens → $0.001 per ask → model reads only what matters
+                                                                  ▲ 92.3% cheaper
+```
+
+**Zero dependencies. Zero API calls. Offline. One `.recallgate` folder.**
+
+---
+
+## Install
+
+```bash
+pip install recallgate
+# or from source
+git clone https://github.com/lamguo/recallgate.git
+cd recallgate && pip install -e .
+```
+
+## Quick start — 10 seconds to value
+
+```bash
+# 1. Init a workspace in your project
+cd my-project && recall-gate init
+
+# 2. Add project rules (they stay in Git-friendly .md files)
+recall-gate add "Keep zero core dependencies." --role coder --priority high
+recall-gate add "Tests use temp fixtures, not example files." --role tester
+recall-gate add "README must match CLI behavior exactly." --role writer
+
+# 3. Generate a 100-token brief for your coding agent
+recall-gate brief "fix CI pipeline test failure" --role tester --budget 100
+```
+
+Paste the output into your AI agent. That's it.
+
+---
+
+## Why you'll use this
+
+### "My AI keeps forgetting the project rules"
+
+```bash
+recall-gate correct "model keeps suggesting requests library — we use stdlib only"
+```
+
+Outputs a <100-token correction brief. Paste it into any AI agent. Problem solved.
+
+### "I'm burning tokens on irrelevant context"
+
+```bash
+recall-gate estimate --task "fix tests" --role tester --json
+```
+
+Returns structured data: `{"full_active_memory_tokens": 1240, "injected_brief_tokens": 95, "estimated_saving_percent": 92.3}`. Know your savings before you inject.
+
+### "Coder, tester, and writer agents need different context"
+
+```bash
+recall-gate brief "fix deployment" --role coder     # sees deployment rules
+recall-gate brief "update docs"   --role writer     # sees README guidelines
+recall-gate brief "review PR"     --role reviewer    # sees audit checklist
+```
+
+Each agent role sees only its relevant memories. Shared rules go to `--role all`.
+
+### "I have 50 memories and don't know what's stale"
+
+```bash
+recall-gate review --apply          # auto-archive low-value memories
+recall-gate list --sort use_count   # see what's never been used
+recall-gate search "fixtures"       # find without opening index.json
+```
+
+---
+
+## Features
+
+| | What | Why it matters |
+|---|---|---|
+| 🎯 | **Role-filtered briefs** | Coder gets coding rules, writer gets docs rules, tester gets test rules |
+| ✂️ | **Token budget control** | Set `default_budget = 100` in config — briefs are hard-capped |
+| 🔄 | **Memory lifecycle** | `active` → `archive` → `trash` → `delete`. Nothing lost by accident |
+| 🔧 | **Edit in place** | `recall-gate edit mem_0001 --priority critical` — no delete+re-create |
+| 🔍 | **Full-text search** | Searches content, short text, keywords, scope, type, priority |
+| 📦 | **JSON output** | `--json` on every command — pipe into scripts, editors, MCP |
+| 📂 | **Git-friendly storage** | Each memory is a `.md` file with YAML frontmatter. Diff, commit, review |
+| 🌐 | **CJK support** | Chinese memory gets readable slugs and meaningful keywords |
+| 🧼 | **Auto-review** | `recall-gate review --apply` archives unused memories automatically |
+
+### Memory lifecycle
+
+```text
+active   → readable by default
+archive  → hidden but recoverable
+trash    → blocked from agents, still recoverable
+deleted  → permanently removed from index and disk
+```
+
+### Role-based routing
+
+Every memory targets one or more roles. `--role all` means everyone sees it.
+
+```bash
+recall-gate brief "fix tests"    --role tester     # only tester memories
+recall-gate brief "update README" --role writer    # only writer memories
+recall-gate brief "review"       --role reviewer   # only reviewer memories
+```
+
+The goal: **Shared outline, private depth.**
+
+---
+
+## Command reference
+
+```
+recall-gate
+  init                           Create workspace
+  add <content>                  Add a memory
+  edit/update <id>               Edit memory fields
+  info <id>                      Full memory details
+  list [--sort] [--reverse]      List memories
+  search <query>                 Full-text search
+  brief <task>                   Token-efficient memory brief
+  correct <issue>                Correction brief (model forgets)
+  estimate                       Token cost estimate
+  review [--apply]               Suggest/apply cleanup
+  archive / trash / restore      Lifecycle commands
+  promote <id>                   Move conversation to project
+  delete <id> --yes              Permanent removal
+
+Global flags:
+  --json      Machine-readable output on all commands
+  --root      Target a specific workspace (for automation)
+```
+
+---
+
+## About injection
+
+`brief` prints plain text by design in v0.1.0. You copy the output into Claude Code, Codex CLI, Cursor, Gemini CLI, Copilot Chat, or any other coding agent.
+
+Automatic injection is intentionally not included in the first version because the core tool should stay local, predictable, and provider-agnostic. Future integrations can add MCP, editor plugins, or agent hooks on top of the same brief engine.
+
+---
+
+## Design philosophy
+
+```text
+Default model calls:       0
+Default API keys:          0
+Default runtime deps:      0
+Default storage:           local Markdown + JSON
+Default tokenizer:         built-in estimator
+Default test discovery:    python -m unittest discover
+```
+
+RecallGate is built to be **cheap, local, and predictable**. No vector database. No LLM calls. No network. No vendor lock-in. You commit your `.recallgate` folder to Git, and every teammate gets the same memory.
+
+### What RecallGate is
+
+- A local memory gate
+- A memory firewall
+- A token-saving brief generator
+- A role-based memory router
+- A stale model memory correction layer
+
+### What RecallGate is not
+
+- Not a hosted memory service
+- Not a vector database
+- Not a full AI agent framework
+- Not a replacement for Claude Code, Codex, Cursor, or Copilot
+- Not a tool that blindly remembers everything
+
+---
+
+## Status
+
+`v0.1.0` — alpha MVP with **31 unit tests, 0 dependencies, and 17 CLI commands**.
+
+**Coming next:** MCP server, editor plugins, auto-conflict detection, and optional AI compression.
+
+## License
+
+MIT

recallgate-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "recallgate"
+version = "0.1.0"
+description = "Token-efficient controllable memory gate for AI coding agents."
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [{name = "RecallGate Contributors"}]
+keywords = ["ai", "agent", "memory", "token", "context", "cli", "coding-agent"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development",
+  "Topic :: Utilities",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/lamguo/recallgate"
+Repository = "https://github.com/lamguo/recallgate"
+Issues = "https://github.com/lamguo/recallgate/issues"
+
+[project.scripts]
+recall-gate = "recallgate.cli:main"
+recallgate = "recallgate.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

recallgate-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

recallgate-0.1.0/setup.py

@@ -0,0 +1,3 @@
+from setuptools import setup
+
+setup()

recallgate-0.1.0/src/recallgate/__init__.py

@@ -0,0 +1,3 @@
+"""RecallGate: token-efficient controllable memory for AI coding agents."""
+
+__version__ = "0.1.0"