From 6230c5c6bc675e1399030543b6c585443fc1efd9 Mon Sep 17 00:00:00 2001 From: Harshit Date: Sat, 30 May 2026 04:03:05 +0530 Subject: [PATCH 1/3] docs: add Engram cognitive memory integration --- packages.yml | 4 + .../integrations/providers/all_providers.mdx | 8 + .../python/integrations/providers/engram.mdx | 42 +++++ .../python/integrations/retrievers/engram.mdx | 167 ++++++++++++++++++ .../python/integrations/retrievers/index.mdx | 1 + 5 files changed, 222 insertions(+) create mode 100644 src/oss/python/integrations/providers/engram.mdx create mode 100644 src/oss/python/integrations/retrievers/engram.mdx diff --git a/packages.yml b/packages.yml index 0ca1804a51..f284934d42 100644 --- a/packages.yml +++ b/packages.yml @@ -100,6 +100,10 @@ packages: js: "@langchain/deepseek" downloads: 697000 downloads_updated_at: "2026-05-18T00:23:32.797657+00:00" +- name: langchain-engram + repo: Harshitk-cp/langchain-engram + downloads: 0 + downloads_updated_at: "2026-05-29T00:00:00.000000+00:00" - name: langchain-exa repo: langchain-ai/langchain path: libs/partners/exa diff --git a/src/oss/python/integrations/providers/all_providers.mdx b/src/oss/python/integrations/providers/all_providers.mdx index e18a0c5f6a..151f8b58e0 100644 --- a/src/oss/python/integrations/providers/all_providers.mdx +++ b/src/oss/python/integrations/providers/all_providers.mdx @@ -417,6 +417,14 @@ Browse the complete collection of integrations available for Python. LangChain P Cloud content collaboration and AI-powered search platform. + + Cognitive memory infrastructure for AI agents — confidence scoring, contradiction detection, and memory lifecycle. + + +```bash pip +pip install langchain-engram +``` + +```bash uv +uv add langchain-engram +``` + + +Set environment variables: + +```bash +export ENGRAM_BASE_URL=http://localhost:8080 # your Engram server +export ENGRAM_API_KEY=mk_... # from POST /v1/setup +``` + +See the [Engram quickstart](https://engram.ai#quickstart) for server setup. + +## Retrievers & Memory + +See the [Engram retriever and memory documentation](/oss/integrations/retrievers/engram) +for `EngramRetriever`, `EngramChatMemory`, and `EngramEntityMemory`. diff --git a/src/oss/python/integrations/retrievers/engram.mdx b/src/oss/python/integrations/retrievers/engram.mdx new file mode 100644 index 0000000000..8edeccdeab --- /dev/null +++ b/src/oss/python/integrations/retrievers/engram.mdx @@ -0,0 +1,167 @@ +--- +title: "Engram retriever" +description: "Integrate with the Engram retriever using LangChain Python." +--- + +# EngramRetriever + +This will help you get started with the Engram [retriever](/oss/langchain/retrieval) +and memory classes. + +Engram is cognitive memory infrastructure for AI agents — tracking not just what +agents know, but how confident they should be, and when to doubt it. + +### Integration details + +| Retriever | Self-host | Cloud offering | Package | +| :--- | :---: | :---: | :---: | +| `EngramRetriever` | ✅ | ✅ | `langchain-engram` | +| `EngramChatMemory` | ✅ | ✅ | `langchain-engram` | +| `EngramEntityMemory` | ✅ | ✅ | `langchain-engram` | + +## Setup + +### Installation + +```bash +pip install langchain-engram +``` + +### Start the server + +```bash +git clone https://github.com/Harshitk-cp/engram.git +cd engram +ENGRAM_SETUP_TOKEN=changeme docker compose up -d + +# Get your API key (run once) +curl -X POST http://localhost:8080/v1/setup \ + -H "X-Setup-Token: changeme" \ + -H "Content-Type: application/json" \ + -d '{"org_name": "My Org"}' +# → {"api_key": "mk_..."} — save this +``` + +### Environment variables + +```bash +export ENGRAM_BASE_URL=http://localhost:8080 +export ENGRAM_API_KEY=mk_... +``` + +## EngramRetriever + +Retrieves memories using Engram's hybrid vector + knowledge-graph recall. +Each result is a `Document` with full metadata: confidence, tier, type, and scores. + +```python +from langchain_engram import EngramRetriever +from langchain.chains import RetrievalQA +from langchain_openai import ChatOpenAI + +retriever = EngramRetriever( + agent_id="your-agent-uuid", + # api_key and base_url read from env if not passed + top_k=5, + min_confidence=0.6, # only surface confident memories +) + +# Standalone retrieval +docs = retriever.invoke("display preferences") +for doc in docs: + print(doc.page_content) + print(f" confidence: {doc.metadata['confidence']:.0%}") + print(f" tier: {doc.metadata['tier']}") # hot / warm / cold + print(f" type: {doc.metadata['memory_type']}") # fact / preference / decision + +# In a RetrievalQA chain +qa = RetrievalQA.from_chain_type(llm=ChatOpenAI(), retriever=retriever) +answer = qa.invoke({"query": "What are the user's display preferences?"}) +``` + +## EngramChatMemory + +Drop-in replacement for `ConversationBufferMemory`. Stores conversation turns as +Engram memories and recalls semantically relevant context on each turn — not a +flat buffer. + +```python +from langchain_engram import EngramChatMemory +from langchain.chains import ConversationChain +from langchain_openai import ChatOpenAI + +memory = EngramChatMemory( + agent_id="your-agent-uuid", + memory_key="history", + top_k=8, + min_confidence=0.5, +) + +chain = ConversationChain(llm=ChatOpenAI(), memory=memory) + +# Memories persist across sessions — not in RAM +chain.predict(input="I always prefer dark mode in all my tools") +chain.predict(input="I'm a backend engineer, mostly Go and Rust") + +# Start a new session — context is recalled from Engram +chain.predict(input="What do you know about my setup?") +# → "You prefer dark mode and work with Go and Rust as a backend engineer." +``` + +## EngramEntityMemory + +Extracts structured entities from conversations using Engram's LLM extraction +pipeline. Instead of storing raw text, it identifies typed memories — preferences, +facts, decisions, constraints. + +```python +from langchain_engram import EngramEntityMemory +from langchain.chains import LLMChain +from langchain_core.prompts import PromptTemplate +from langchain_openai import ChatOpenAI + +memory = EngramEntityMemory( + agent_id="your-agent-uuid", + memory_key="entities", + min_confidence=0.6, +) + +prompt = PromptTemplate( + input_variables=["entities", "input"], + template=( + "You are a helpful assistant.\n\n" + "What you know about this user:\n{entities}\n\n" + "Human: {input}\nAI:" + ), +) + +chain = LLMChain(llm=ChatOpenAI(), prompt=prompt, memory=memory) +chain.predict(input="I work in Go and need a REST API for a todo app") +chain.predict(input="What stack should I use for the database layer?") +# LLM sees: "Known entities and facts: +# - User is building a REST API todo app [fact, 93% confident] +# - User works in Go [fact, 91% confident]" +``` + +## API key scopes + +| Key prefix | Scopes | Use case | +|---|---|---| +| `mk_...` | admin + read + write | Server setup, key management | +| `rk_...` | user-chosen | Production agents (read + write is sufficient) | + +For LangChain usage, a `rk_` key with `read` and `write` scopes is sufficient: + +```python +from engram import Engram +client = Engram() # uses mk_ key from env +result = client.keys.create(name="langchain-bot", scopes=["read", "write"]) +print(result.api_key) # rk_... — use this as ENGRAM_API_KEY +``` + +## Related links + +- [Engram documentation](https://engram.ai) +- [Python SDK (engram.to)](https://pypi.org/project/engram.to/) +- [GitHub](https://github.com/Harshitk-cp/langchain-engram) +- [Provider page](/oss/integrations/providers/engram) diff --git a/src/oss/python/integrations/retrievers/index.mdx b/src/oss/python/integrations/retrievers/index.mdx index 11cbf2740c..81eb050e56 100644 --- a/src/oss/python/integrations/retrievers/index.mdx +++ b/src/oss/python/integrations/retrievers/index.mdx @@ -50,6 +50,7 @@ The below retrievers will search over an external index (e.g., constructed from + From f67b1f42b6dd3eb3e41ce4e5c173c3c3dc4053d0 Mon Sep 17 00:00:00 2001 From: Harshit Date: Sat, 30 May 2026 13:29:57 +0530 Subject: [PATCH 2/3] docs: remove deprecated BaseMemory classes from Engram integration --- .../python/integrations/providers/engram.mdx | 15 +- .../python/integrations/retrievers/engram.mdx | 135 ++++++------------ 2 files changed, 50 insertions(+), 100 deletions(-) diff --git a/src/oss/python/integrations/providers/engram.mdx b/src/oss/python/integrations/providers/engram.mdx index ebe6936622..59cebef5d6 100644 --- a/src/oss/python/integrations/providers/engram.mdx +++ b/src/oss/python/integrations/providers/engram.mdx @@ -4,9 +4,8 @@ description: "Integrate with Engram using LangChain Python." --- [Engram](https://engram.ai) is cognitive memory infrastructure for AI agents. -Unlike simple vector stores, Engram tracks **confidence scores**, detects -**contradictions**, and manages **memory lifecycle** — so agents know what they -know and when to doubt it. +Engram tracks **confidence scores**, detects **contradictions**, and manages +**memory lifecycle** — so agents know what they know and when to doubt it. Key capabilities: - 4-type cognitive model: semantic, episodic, procedural, and working memory @@ -30,13 +29,13 @@ uv add langchain-engram Set environment variables: ```bash -export ENGRAM_BASE_URL=http://localhost:8080 # your Engram server -export ENGRAM_API_KEY=mk_... # from POST /v1/setup +export ENGRAM_BASE_URL=http://localhost:8080 +export ENGRAM_API_KEY=mk_... ``` See the [Engram quickstart](https://engram.ai#quickstart) for server setup. -## Retrievers & Memory +## Retrievers -See the [Engram retriever and memory documentation](/oss/integrations/retrievers/engram) -for `EngramRetriever`, `EngramChatMemory`, and `EngramEntityMemory`. +See the [EngramRetriever documentation](/oss/integrations/retrievers/engram) for +memory-backed retrieval with confidence filtering and hybrid recall. diff --git a/src/oss/python/integrations/retrievers/engram.mdx b/src/oss/python/integrations/retrievers/engram.mdx index 8edeccdeab..5a276e9a2d 100644 --- a/src/oss/python/integrations/retrievers/engram.mdx +++ b/src/oss/python/integrations/retrievers/engram.mdx @@ -5,19 +5,18 @@ description: "Integrate with the Engram retriever using LangChain Python." # EngramRetriever -This will help you get started with the Engram [retriever](/oss/langchain/retrieval) -and memory classes. +This will help you get started with the Engram [retriever](/oss/langchain/retrieval). Engram is cognitive memory infrastructure for AI agents — tracking not just what -agents know, but how confident they should be, and when to doubt it. +agents know, but how confident they should be, and when to doubt it. Each retrieved +memory is a `Document` carrying confidence score, memory tier, and relevance scores +from Engram's hybrid vector + knowledge-graph recall. ### Integration details | Retriever | Self-host | Cloud offering | Package | | :--- | :---: | :---: | :---: | | `EngramRetriever` | ✅ | ✅ | `langchain-engram` | -| `EngramChatMemory` | ✅ | ✅ | `langchain-engram` | -| `EngramEntityMemory` | ✅ | ✅ | `langchain-engram` | ## Setup @@ -39,7 +38,7 @@ curl -X POST http://localhost:8080/v1/setup \ -H "X-Setup-Token: changeme" \ -H "Content-Type: application/json" \ -d '{"org_name": "My Org"}' -# → {"api_key": "mk_..."} — save this +# → {"api_key": "mk_..."} ``` ### Environment variables @@ -49,15 +48,10 @@ export ENGRAM_BASE_URL=http://localhost:8080 export ENGRAM_API_KEY=mk_... ``` -## EngramRetriever - -Retrieves memories using Engram's hybrid vector + knowledge-graph recall. -Each result is a `Document` with full metadata: confidence, tier, type, and scores. +## Instantiation ```python from langchain_engram import EngramRetriever -from langchain.chains import RetrievalQA -from langchain_openai import ChatOpenAI retriever = EngramRetriever( agent_id="your-agent-uuid", @@ -65,99 +59,56 @@ retriever = EngramRetriever( top_k=5, min_confidence=0.6, # only surface confident memories ) +``` + +## Usage -# Standalone retrieval +```python docs = retriever.invoke("display preferences") for doc in docs: print(doc.page_content) print(f" confidence: {doc.metadata['confidence']:.0%}") - print(f" tier: {doc.metadata['tier']}") # hot / warm / cold - print(f" type: {doc.metadata['memory_type']}") # fact / preference / decision - -# In a RetrievalQA chain -qa = RetrievalQA.from_chain_type(llm=ChatOpenAI(), retriever=retriever) -answer = qa.invoke({"query": "What are the user's display preferences?"}) + print(f" tier: {doc.metadata['tier']}") # hot / warm / cold + print(f" type: {doc.metadata['memory_type']}") # fact / preference / decision + print(f" score: {doc.metadata.get('score', 'n/a')}") ``` -## EngramChatMemory - -Drop-in replacement for `ConversationBufferMemory`. Stores conversation turns as -Engram memories and recalls semantically relevant context on each turn — not a -flat buffer. +### In a RetrievalQA chain ```python -from langchain_engram import EngramChatMemory -from langchain.chains import ConversationChain -from langchain_openai import ChatOpenAI - -memory = EngramChatMemory( - agent_id="your-agent-uuid", - memory_key="history", - top_k=8, - min_confidence=0.5, -) - -chain = ConversationChain(llm=ChatOpenAI(), memory=memory) - -# Memories persist across sessions — not in RAM -chain.predict(input="I always prefer dark mode in all my tools") -chain.predict(input="I'm a backend engineer, mostly Go and Rust") - -# Start a new session — context is recalled from Engram -chain.predict(input="What do you know about my setup?") -# → "You prefer dark mode and work with Go and Rust as a backend engineer." -``` - -## EngramEntityMemory - -Extracts structured entities from conversations using Engram's LLM extraction -pipeline. Instead of storing raw text, it identifies typed memories — preferences, -facts, decisions, constraints. - -```python -from langchain_engram import EngramEntityMemory -from langchain.chains import LLMChain -from langchain_core.prompts import PromptTemplate +from langchain.chains import RetrievalQA from langchain_openai import ChatOpenAI -memory = EngramEntityMemory( - agent_id="your-agent-uuid", - memory_key="entities", - min_confidence=0.6, -) - -prompt = PromptTemplate( - input_variables=["entities", "input"], - template=( - "You are a helpful assistant.\n\n" - "What you know about this user:\n{entities}\n\n" - "Human: {input}\nAI:" - ), -) - -chain = LLMChain(llm=ChatOpenAI(), prompt=prompt, memory=memory) -chain.predict(input="I work in Go and need a REST API for a todo app") -chain.predict(input="What stack should I use for the database layer?") -# LLM sees: "Known entities and facts: -# - User is building a REST API todo app [fact, 93% confident] -# - User works in Go [fact, 91% confident]" +qa = RetrievalQA.from_chain_type(llm=ChatOpenAI(), retriever=retriever) +answer = qa.invoke({"query": "What are the user's display preferences?"}) ``` -## API key scopes - -| Key prefix | Scopes | Use case | -|---|---|---| -| `mk_...` | admin + read + write | Server setup, key management | -| `rk_...` | user-chosen | Production agents (read + write is sufficient) | - -For LangChain usage, a `rk_` key with `read` and `write` scopes is sufficient: - -```python -from engram import Engram -client = Engram() # uses mk_ key from env -result = client.keys.create(name="langchain-bot", scopes=["read", "write"]) -print(result.api_key) # rk_... — use this as ENGRAM_API_KEY -``` +### Document metadata fields + +| Field | Type | Description | +| :--- | :--- | :--- | +| `memory_id` | `str` | UUID of the memory | +| `agent_id` | `str` | Owning agent UUID | +| `memory_type` | `str` | `fact` / `preference` / `decision` / `constraint` | +| `confidence` | `float` | Calibrated confidence score (0–1) | +| `tier` | `str` | `hot` / `warm` / `cold` | +| `source` | `str` | Origin of the memory | +| `score` | `float` | Combined recall score | +| `vector_score` | `float` | Vector similarity component | +| `graph_score` | `float` | Graph traversal component | +| `created_at` | `str` | ISO 8601 timestamp | + +## Configuration + +| Parameter | Default | Description | +| :--- | :--- | :--- | +| `agent_id` | required | Engram agent UUID | +| `api_key` | `ENGRAM_API_KEY` env | `mk_` or `rk_` prefixed API key | +| `base_url` | `ENGRAM_BASE_URL` env | Engram server URL | +| `top_k` | `10` | Max memories to return | +| `min_confidence` | `None` | Confidence floor (0–1) | +| `memory_type` | `None` | Filter by type: `fact`, `preference`, `decision`, `constraint` | +| `graph_weight` | `None` | Graph/vector blend (0–1); server default 0.4/0.6 | ## Related links From 05e28d394eba7f2ea8c934b7cf33839d3391a2fd Mon Sep 17 00:00:00 2001 From: Harshit Date: Sat, 30 May 2026 13:38:09 +0530 Subject: [PATCH 3/3] fix: remove spaces around dashes | lint fix --- src/oss/python/integrations/providers/engram.mdx | 2 +- src/oss/python/integrations/retrievers/engram.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/oss/python/integrations/providers/engram.mdx b/src/oss/python/integrations/providers/engram.mdx index 59cebef5d6..df4d5a063c 100644 --- a/src/oss/python/integrations/providers/engram.mdx +++ b/src/oss/python/integrations/providers/engram.mdx @@ -5,7 +5,7 @@ description: "Integrate with Engram using LangChain Python." [Engram](https://engram.ai) is cognitive memory infrastructure for AI agents. Engram tracks **confidence scores**, detects **contradictions**, and manages -**memory lifecycle** — so agents know what they know and when to doubt it. +**memory lifecycle**—so agents know what they know and when to doubt it. Key capabilities: - 4-type cognitive model: semantic, episodic, procedural, and working memory diff --git a/src/oss/python/integrations/retrievers/engram.mdx b/src/oss/python/integrations/retrievers/engram.mdx index 5a276e9a2d..12bd8fef54 100644 --- a/src/oss/python/integrations/retrievers/engram.mdx +++ b/src/oss/python/integrations/retrievers/engram.mdx @@ -7,7 +7,7 @@ description: "Integrate with the Engram retriever using LangChain Python." This will help you get started with the Engram [retriever](/oss/langchain/retrieval). -Engram is cognitive memory infrastructure for AI agents — tracking not just what +Engram is cognitive memory infrastructure for AI agents—tracking not just what agents know, but how confident they should be, and when to doubt it. Each retrieved memory is a `Document` carrying confidence score, memory tier, and relevance scores from Engram's hybrid vector + knowledge-graph recall.