{
  "markdown": "<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/GiulioDER/RE-call/master/docs/banner.png\" alt=\"RE-call: memory that knows when not to guess\" width=\"900\">\n</p>\n\n<!-- mcp-name: io.github.GiulioDER/re-call -->\n\n<p align=\"center\">\n  <b>Memory that abstains instead of guessing.</b><br>\n  RE-call is agent memory on your own PostgreSQL with pgvector. Each result carries a verdict,\n  confidence, and provenance, while unsupported questions are refused instead of answered by the\n  nearest match.\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/GiulioDER/RE-call/actions/workflows/ci.yml\"><img src=\"https://github.com/GiulioDER/RE-call/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"></a>\n  <a href=\"https://pypi.org/project/recall-rag/\"><img src=\"https://img.shields.io/pypi/v/recall-rag\" alt=\"PyPI version\"></a>\n  <a href=\"https://github.com/GiulioDER/RE-call/blob/master/LICENSE\"><img src=\"https://img.shields.io/badge/License-Apache%202.0-blue.svg\" alt=\"License: Apache 2.0\"></a>\n  <img src=\"https://img.shields.io/badge/python-3.11%2B-blue\" alt=\"Python 3.11+\">\n  <img src=\"docs/postgresql-badge.svg\" alt=\"PostgreSQL + pgvector\">\n</p>\n\n<p align=\"center\">\n  <a href=\"#what-is-re-call\">What it is</a>\n  &nbsp;·&nbsp;\n  <a href=\"#how-it-works\">How it works</a>\n  &nbsp;·&nbsp;\n  <a href=\"#quickstart\">Try the demo</a>\n  &nbsp;·&nbsp;\n  <a href=\"#install-and-integrate\">Install and integrate</a>\n</p>\n\n## What is RE-call\n\nRE-call is a retrieval and memory layer for agents that need to know when a result is safe to use.\nIt stores source documents in your PostgreSQL database, indexes them with pgvector, and keeps\nvalidity and lineage attached to every hit.\n\nPlain vector search returns nearby text. RE-call also asks whether that text is current, supported,\nand trustworthy enough for the query. A superseded claim comes back marked `superseded`; a result\nthat does not clear the calibrated trust gate becomes `ABSTAIN` with a reason. Declared supersession makes the current memory win over stale but similar memory.\n\nThe core path does not require a memory-layer LLM call. Local embeddings and hybrid retrieval are\navailable by default. Hosted embeddings, learned sparse retrieval, reranking, entailment judging,\nreasoning, and structured fact application are opt in.\n\n## How it works\n\nRead the diagrams from top to bottom. The solid spine is the default path. Dashed arrows show a\nbinding or conditional relationship. Optional consumer modules branch from trusted evidence, while\nretrieval upgrades attach at the stages named in the table. Nothing bypasses the generation or trust\nboundary.\n\n```mermaid\nflowchart TB\n    subgraph BUILD[\"1. Build and certify a generation\"]\n        direction LR\n        SOURCE[\"Corpus<br/>memo files + frontmatter\"] --> PREP[\"Validate + manifest<br/>chunk + embed\"]\n        PREP --> GEN[(\"Immutable generation<br/>PostgreSQL + pgvector\")]\n        GEN --> CAL[\"Calibration<br/>published for this generation\"]\n    end\n\n    subgraph READ[\"2. Serve every query\"]\n        direction LR\n        CLIENT[\"Agent or application\"] --> ACCESS[\"Python API · CLI · MCP\"]\n        ACCESS --> PRECHECK[\"Pin active generation<br/>require published calibration\"]\n        PRECHECK -->|\"ready\"| RETRIEVE[\"Hybrid retrieval<br/>dense vectors + Postgres full text\"]\n        PRECHECK -->|\"not ready\"| REFUSE[\"REFUSE before retrieval<br/>reason returned\"]\n        RETRIEVE --> GATE{\"Calibrated trust gate<br/>validity + supersession + confidence\"}\n        GATE -->|\"trusted\"| TRUSTED[\"Trusted evidence<br/>verdict + provenance\"]\n        GATE -->|\"unsupported or stale\"| ABSTAIN[\"ABSTAIN<br/>reason returned\"]\n    end\n\n    GEN -. \"active snapshot\" .-> PRECHECK\n    CAL -. \"threshold bound to generation\" .-> PRECHECK\n\n    classDef core fill:#e8f3ff,stroke:#2b6cb0,color:#102a43,stroke-width:1px;\n    classDef trust fill:#e8f5e9,stroke:#2f855a,color:#163b27,stroke-width:1px;\n    classDef stop fill:#fff1f2,stroke:#c53030,color:#63171b,stroke-width:1px;\n    class SOURCE,PREP,GEN,CAL,CLIENT,ACCESS,PRECHECK,RETRIEVE core;\n    class GATE,TRUSTED trust;\n    class REFUSE,ABSTAIN stop;\n```\n\nThe optional consumers form a separate branch from trusted evidence:\n\n```mermaid\nflowchart LR\n    TRUSTED[\"Trusted evidence\"] --> REASON[\"Bounded reasoning<br/>optional graph expansion + citation validation\"]\n    REASON --> ANSWER[\"Cited answer<br/>review or ABSTAIN\"]\n    TRUSTED --> BUNDLE[\"Citable evidence<br/>recall_evidence\"]\n    BUNDLE --> CARDS[\"Immutable evidence cards<br/>source digest + lineage\"]\n    CARDS --> CONTROLLER[\"Provenance controller<br/>review + recheck\"]\n    CONTROLLER --> LEDGER[(\"Append only fact ledger<br/>asserted · refused · superseded\")]\n    LEDGER --> CURRENT[\"Current facts<br/>projection\"]\n    LEDGER -. \"authorized events\" .-> OUTBOX[\"Materialization outbox<br/>bounded recovery\"]\n    OUTBOX --> MATERIALIZER[\"Downstream materializer\"]\n\n    classDef optional fill:#fff8e1,stroke:#b7791f,color:#5f370e,stroke-width:1px;\n    classDef trust fill:#e8f5e9,stroke:#2f855a,color:#163b27,stroke-width:1px;\n    class TRUSTED,LEDGER trust;\n    class REASON,ANSWER,BUNDLE,CARDS,CONTROLLER,CURRENT,OUTBOX,MATERIALIZER optional;\n```\n\nThe opt in choices attach to different points in the system:\n\n| Optional module | Attaches to | What it adds |\n|---|---|---|\n| Hosted embedder | Build and query | Remote model calls for embeddings. Query and corpus text may leave the environment. |\n| Learned sparse retrieval, SPLADE | Hybrid retrieval | A learned term weighted retrieval leg in addition to dense vectors and Postgres full text. |\n| Reranker | After candidate fusion | Reorders the fused candidates with a cross encoder. |\n| Entailment judge | After the trust decision | Demotes high similarity near misses that do not answer the question. |\n| Evidence Graph version one | Reasoning | Adds bounded, generation bound one hop expansion. Expanded evidence returns through trust and citation checks. |\n| Structured fact application | Evidence cards | Lets a reviewed fact pass through the provenance controller into the append only ledger. |\n\nIn practical terms:\n\n1. A manifest turns a corpus into an immutable, tenant scoped generation. Calibration is published\n   for that generation before strict serving.\n2. A query goes through an integration surface, pins the active generation, retrieves candidates,\n   and passes through validity, supersession, confidence, and calibration checks.\n3. The result is trusted evidence or an abstention with a reason. Optional consumers can reason over\n   the evidence, create citable cards, or propose a reviewed structured fact. The provenance\n   controller rechecks the evidence before the append only ledger accepts or refuses the fact.\n\nThe detailed architecture is in [docs/WRITEUP.md](docs/WRITEUP.md). The provenance boundary is\ndocumented in [docs/PROVENANCE_CONTROLLER.md](docs/PROVENANCE_CONTROLLER.md), and the complete\nAPI is in [docs/API.md](docs/API.md).\n\n## Quickstart\n\nPrerequisites: Python 3.11 or newer, Docker, and a Docker installation able to run PostgreSQL with\npgvector.\n\n```bash\npip install \"recall-rag[fastembed]\"\nrecall quickstart\n```\n\nThe demo starts a throwaway database, indexes a small corpus included in the package, and runs\nthree searches. It includes a normal answer, a stale claim that is returned as superseded, and a\nquestion that is refused. The demo uses development trust and changes no personal files.\n\nRemove the demo database when finished:\n\n```bash\nrecall quickstart --remove\n```\n\nAlready have PostgreSQL with pgvector? Use `recall quickstart --existing-dsn <dsn>` instead. The\ndemo is intentionally separate from a real install and is not calibrated for your data.\n\n## Install and integrate\n\nFor your own corpus, install the package, provide PostgreSQL with pgvector, and run the guided setup wizard:\n\n```bash\npip install \"recall-rag[fastembed]\"\nrecall setup\n```\n\nThe wizard applies the schema, asks for the embedder and retrieval options, indexes the corpus,\noffers calibration, and registers the selected agent integration. When the wizard asks whether to calibrate, use a labeled query file that refers to the corpus you are installing. Calibration fitted\nto the bundled demo is only an example, not a certification for your data. The schema uses an\nordered SQL migration path and pre-tenancy tables are migrated in place.\n\nFor Docker, an existing database, headless provisioning, manual calibration, and troubleshooting,\nsee [docs/INSTALLATION.md](docs/INSTALLATION.md) and [docs/WIZARD.md](docs/WIZARD.md).\n\n### Choose an integration\n\n| Use case | Install | Next step |\n|---|---|---|\n| CLI and Python | `pip install \"recall-rag[fastembed]\"` | Run `recall setup`, then use `recall search` or the [Python API](docs/API.md). |\n| MCP server | `pip install \"recall-rag[fastembed,mcp]\"` | Run `recall setup` or follow [the MCP guide](docs/USING_WITH_CLAUDE.md). |\n| Claude Code | The MCP install plus the plugin | Install the package, then run the plugin commands below. `recall setup` configures the project corpus and hooks. |\n| Claude Desktop | The MCP install | Run setup, add the server block from [the Claude guide](docs/USING_WITH_CLAUDE.md), then restart Claude Desktop. |\n| Codex | `pip install \"recall-rag[fastembed]\"` | Run `recall setup` from the project. It detects Codex and installs the MCP server, plugin bundle, skills, and lifecycle hooks. |\n| Claude Agent SDK | `pip install \"recall-rag[agent,fastembed]\"` | Use the in-process integration in [USING_WITH_AGENT_SDK.md](docs/USING_WITH_AGENT_SDK.md). |\n| LangChain | `pip install \"recall-rag[langchain,fastembed]\"` | Use `recall.integrations.langchain.RecallRetriever`. |\n| LlamaIndex | `pip install \"recall-rag[llamaindex,fastembed]\"` plus `llama-index-core` | Use `recall.integrations.llamaindex.RecallRetriever`. |\n| Windows desktop installer | `pip install \"recall-rag[desktop]\"` | Run `recall-install`. See [the wizard guide](docs/WIZARD.md). |\n\n#### Claude Code\n\nInside Claude Code, install the plugin after installing the Python package:\n\n```text\n/plugin marketplace add GiulioDER/RE-call\n/plugin install recall@re-call\n```\n\nThe plugin supplies the MCP server, memory search skill, and lifecycle hooks. `recall setup` still\nneeds to run against the project and database that Claude should use. The plugin keeps credentials\nout of the repository. Details and manual wiring are in [plugin/README.md](plugin/README.md).\n\n#### Codex\n\nRun `recall setup` from the project. When Codex is detected, setup installs the Codex MCP server,\nplugin bundle, memory skills, and hooks into the user configuration. Restart Codex afterward. The\nCodex and Claude Code integrations share the same memo format and trust layer. See\n[docs/CODEX_RECALL_INTEGRATION.md](docs/CODEX_RECALL_INTEGRATION.md).\n\n#### Claude Agent SDK\n\nThe SDK integration runs the same tools in process and does not start an MCP server:\n\n```python\nfrom recall_agent import RecallAgentMemory\n\nwith RecallAgentMemory.from_env() as memory:\n    options = memory.options()\n```\n\nSee [docs/USING_WITH_AGENT_SDK.md](docs/USING_WITH_AGENT_SDK.md) for the complete example and\nwrite-tool boundaries.\n\n#### LangChain and LlamaIndex\n\nBoth adapters use the same trusted retrieval path. If trust abstains, they return no document by\ndefault, and returned documents retain verdict, confidence, cosine, and supersession metadata.\nSee [docs/API.md](docs/API.md) for the supported classes and methods.\n\n### If an install is not working\n\n```bash\nrecall doctor\n```\n\nThe doctor checks the interpreter, console scripts, embedder, Docker, database, pgvector, schema,\nconfigured table and tenant, calibration, and agent registration. It changes nothing and prints the\nrepair command for each problem.\n\n## Product surface\n\n| Area | What ships |\n|---|---|\n| Retrieval | Dense vectors plus Postgres full text with hybrid RRF, optional learned sparse retrieval and reranking, validity, calibrated confidence, provenance, and trust verdicts. |\n| Storage | PostgreSQL with pgvector, immutable generations, migrations, incremental indexing, pruning, and source erasure. |\n| Agent access | CLI, MCP, Claude Code, Claude Desktop, Codex, Claude Agent SDK, LangChain, LlamaIndex, and Python APIs. |\n| Structured facts | Citable evidence cards, provenance controller, append only fact ledger, current fact projection, and optional materialization outbox. |\n| Quality | Real pgvector integration tests, type checking, linting, dependency audit, and a claim gate that checks published evidence in CI. |\n\nRE-call is not a hosted memory service, a dashboard, or an automatic truth extractor. It does not\nrewrite corpus metadata from an agent's inference. Reasoning is opt in, citation constrained, and\nreview aware. See [docs/PRODUCTION.md](docs/PRODUCTION.md) for deployment boundaries.\n\n## Read next\n\n| Need | Document |\n|---|---|\n| Full documentation map | [docs/README.md](docs/README.md) |\n| Installation and provisioning | [docs/INSTALLATION.md](docs/INSTALLATION.md) |\n| Python, CLI, and MCP reference | [docs/API.md](docs/API.md) |\n| Trust, architecture, and provenance | [docs/WRITEUP.md](docs/WRITEUP.md), [docs/PROVENANCE_CONTROLLER.md](docs/PROVENANCE_CONTROLLER.md) |\n| Calibration and generations | [docs/FIRST_CALIBRATION.md](docs/FIRST_CALIBRATION.md), [docs/CALIBRATION.md](docs/CALIBRATION.md), [docs/GENERATIONS.md](docs/GENERATIONS.md) |\n| Security and operations | [docs/AUTH.md](docs/AUTH.md), [docs/MIGRATIONS.md](docs/MIGRATIONS.md), [docs/OPERATING_MODES.md](docs/OPERATING_MODES.md) |\n| Measurements and limits | [docs/EVIDENCE.md](docs/EVIDENCE.md), [results/FINDINGS.md](results/FINDINGS.md) |\n| Upgrade notes | [CHANGELOG.md](CHANGELOG.md) |\n\nPublished numbers are tied to committed artifacts, and the claim gate checks them in CI. Benchmark\ninterpretation and limits belong in [docs/EVIDENCE.md](docs/EVIDENCE.md), not in this overview.\n\n## Citation\n\nIf you describe RE-call in a paper, post, talk, or README of your own, cite the project and credit\nGiulio D'Erme. Use [CITATION.cff](CITATION.cff) as the canonical citation source.\n\n## License\n\nApache 2.0 license. See [LICENSE](LICENSE), and keep [NOTICE](NOTICE) with redistributed derivative\nworks.\n",
  "bytes": 14179,
  "sha": "ccae68fb87af3dc653dc47e74a31d8976bc9f1536e4171639cb396e4c4f15c14",
  "repo_slug": "giulioder/re-call",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_giulioder_re_call_1cc19035/readme"
}