cognee.remember()

async def remember(
    data: Union[
        BinaryIO,
        list[BinaryIO],
        str,
        list[str],
        DataItem,
        list[DataItem],
        MemoryEntry,
        PresortReport,
        dict,
    ],
    dataset_name: str = "main_dataset",
    *,
    session_id: Optional[str] = None,
    chunk_size: Optional[int] = None,
    chunker: Optional[Any] = None,
    custom_prompt: Optional[str] = None,
    run_in_background: bool = False,
    self_improvement: bool = True,
    session_ids: Optional[List[str]] = None,
    dry_run: Union[bool, Literal["presort"]] = False,
    raise_on_error: bool = True,
    **kwargs,
) -> Union[RememberResult, DryRunEstimate, PresortReport, dict]

Description

remember() is the main ingestion entry point in Cognee v1.0.

Without session_id, it stores permanent memory by running the ingestion pipeline for you.
With session_id, it stores session memory in the cache for fast short-term retrieval.
When self_improvement=True, Cognee also runs improve() to enrich the graph or bridge session content into permanent memory.

Because permanent memory is built through cognify(), the cognify feature flags apply to remember() too. Notably, setting CONTRADICTION_DETECTION=true makes every remember() call check the facts it just stored against the ones already in the graph and record each conflict as a contradicts edge — see Contradiction detection — and PROVENANCE_TRACKING=true makes it append an audit-ledger entry for every document, chunk, entity, and relationship it produced, see Provenance ledger. Both off by default. For the full behavior walkthrough, see Remember.

Parameters

Union[BinaryIO, list[BinaryIO], str, list[str], DataItem, list[DataItem], MemoryEntry, PresortReport, dict]

required

Content to store. Supports text, file paths, URLs, file-like objects, DataItem values, lists of supported inputs, and typed session-memory entries. A GitHub/GitLab repository URL is recognised by shape, shallow-cloned, and indexed as a code graph rather than fetched as a web page — see add() and the Code Graph guide. A PresortReport (or a path ending in .presort.json) is recognised as a presort report and applied instead of ingested — see Folder presort.

str

default:"'main_dataset'"

Target dataset for permanent memory or for session-to-graph bridging.

Optional[str]

default:"None"

Enables session-memory mode. When set, content is written to the session cache instead of going straight into the permanent graph.

Optional[int]

default:"None"

Maximum chunk size for permanent ingestion. When omitted, Cognee uses its default chunking behavior.

Optional[Any]

default:"None"

Custom chunking strategy for permanent ingestion.

Optional[str]

default:"None"

Overrides the prompt used during graph extraction.

bool

default:"False"

Starts the work asynchronously and returns a RememberResult you can await later.

bool

default:"True"

When enabled, runs improve() automatically after storage to enrich the graph or bridge session content.

Optional[List[str]]

default:"None"

Session IDs to sync newly enriched graph knowledge back into during the improvement pass.

Union[bool, Literal['presort']]

default:"False"

When True, return a DryRunEstimate of LLM token usage and rough cost instead of ingesting data. No LLM calls are made, no data is ingested, and no graph is written. See Dry-run cost estimation.When "presort", treat data as a folder path and return a PresortReport instead of ingesting. This is a separate feature that happens to share the parameter — see Folder presort.

bool

default:"True"

Forwarded to the internal cognify() step. When true, a blocking remember() whose graph build errored raises CognifyFailedError instead of returning a RememberResult with status="errored". Set False to keep the previous behavior. See Failed runs.

Dry-run cost estimation

Pass dry_run=True to preview the LLM token usage and rough USD cost of a permanent remember() run without ingesting data, making LLM calls, or writing the graph:

import cognee

estimate = await cognee.remember("Einstein was born in Ulm.", dry_run=True)
print(estimate)                    # human-readable summary table
print(estimate.estimated_cost_usd)
print(estimate.to_dict())          # JSON-serializable dict

The call returns a DryRunEstimate with a stage-level breakdown (structured_graph_extraction and chunk_summarization). Its operation field is "remember"; the full field reference is documented under cognify() → Dry-run cost estimation. Supported inputs: raw text, local text files, and file:// URIs. Dataset resolution for the estimate is read-only. The estimator mirrors real ingestion routing, so a bare path string is only read from disk when that file exists. An absolute-looking string that does not exist (for example "/remember to call the dentist") is priced as raw text instead of failing, matching what a real run would ingest and bill. Local path inputs are also subject to ACCEPT_LOCAL_FILE_PATH, and the estimator detects absolute paths the same way real ingestion does — including Windows drive-letter paths such as C:\notes.txt. When the flag is disabled, a file:// URI or a string pointing at an existing absolute local file raises rather than being estimated; an existing relative path, and any string that is not an existing file, are still priced as raw text. Rejected inputs (raise a ValueError rather than being silently mis-estimated):

session_id (session memory) — dry run only supports the permanent add+cognify path
Typed MemoryEntry values and MemorySource imports
Any content_type override, including content_type="skills" and content_type="code"
Remote (serve()) mode — call cognee.disconnect() to estimate locally
Remote URLs (http/https/s3), directories, and binary formats (PDF, images, audio, Office documents) that a real run would fetch, walk, or transcribe

The estimate excludes the extra LLM calls that improve() makes when self_improvement=True (the default), as well as embedding costs.

Folder presort

Presort is a two-phase pre-ingestion pass for messy folders. It shares the dry_run parameter with the cost estimator above, but is an unrelated feature: nothing is priced, and the folder is inspected rather than ingested. For a runnable walkthrough of both phases, see the Folder Presort guide.

import os

import cognee

# Presort only reads inside its permitted roots, and ~/Downloads is not one of
# them by default — name it explicitly before scanning.
os.environ["COGNEE_ALLOWED_LOCAL_FILE_ROOTS"] = os.path.expanduser("~/Downloads")

# Phase 1 — analyze. Reads the folder, never writes to it.
report = await cognee.remember("~/Downloads", dry_run="presort")
print(report.summary())

# Review and adjust the apply decisions on the report itself
report.exclude_pii = True
report.apply_groups = [group.name for group in report.groups if group.kind != "code_project"]

# Phase 2 — apply. One dataset per proposed group.
results = await cognee.remember(report)   # {dataset_name: RememberResult}

Pass auto_apply=True to do both in one call. The report is still produced and persisted first, and the ingest outcomes ride back on report.apply_results ({dataset_name: RememberResult}):

report = await cognee.remember("~/Downloads", dry_run="presort", auto_apply=True)
print(report.apply_results)

The analyze phase is deterministic by default — no LLM or embedding configuration is required. Pass use_llm=True to add LLM content classification, deeper PII detection, and semantic grouping.

The report

remember(folder, dry_run="presort") returns a PresortReport (cognee.tasks.presort.models). It is a Pydantic model, so to_dict(), to_json(), save(path), and PresortReport.from_json(source) are all available, and summary() returns the counts the CLI prints.

Field	Contents
`files`	One `FileRecord` per scanned file: path, extension, MIME type, size, `family` bucket, `content_hash`, `cognee_status` (`new` / `staged` / `cognified` / `unknown`), and `known_in_datasets`
`junk`	Files skipped by the scan, each with a `reason`
`duplicates`	`DuplicateCluster` entries grouping identical content by hash. Paths are ordered — the first is the copy apply keeps
`versions`	`VersionCandidate` entries (`report_v2.pdf` and friends), ordered oldest → newest by modification time
`pii`	`PiiFinding` entries with `category`, `severity`, and `source` (`filename` / `content` / `llm`). Samples are always redacted; raw matches are never stored in the report
`groups`	`ProposedGroup` entries — the proposed `dataset_name`, `kind` (`code_project` / `folder` / `extension_family` / `semantic`), and member file paths
`relationships`	The generic relation view written to the graph by `apply_graph=True`, keyed by the relation names on the relationship spec
`skip_duplicates`, `exclude_pii`, `apply_groups`	The apply decisions, settable on the report before handing it back
`report_path`	Where the report was persisted, if it was
`warnings`	Degradations and skipped checks raised during the scan

Unless SYSTEM_ROOT_DIRECTORY is unset or on S3, the report is also saved automatically to <SYSTEM_ROOT_DIRECTORY>/presort/<scan_id>.presort.json, so the analyze result survives even when apply fails.

Applying a report

remember() recognises a report passed as data in three shapes: a PresortReport object, a dict carrying the presort_report: true marker, or a path ending in .presort.json. Ordinary .json ingestion is unaffected — only that exact suffix is treated as a report. Apply ingests each selected group into its proposed dataset through the normal add → cognify (→ improve) chain with incremental_loading=True, so re-applying is idempotent: content the report marked cognified is skipped by the pipeline. Each group’s items are tagged with the node set ["presort", "<group name>"]. It returns {dataset_name: RememberResult}, not a single RememberResult; with apply_graph=True the relationship graph’s outcome rides along under the extra key presort_graph.

Presort options

Analyze-phase keywords (dry_run="presort"):

Option	Type	Default	What it does
`include_subdirectories`	`bool`	`True`	Walk subdirectories, not just the top level
`use_llm`	`bool`	`False`	Add LLM content classification, deeper PII detection, and semantic grouping
`detect_pii`	`bool`	`True`	Run personal-data detection
`check_existing`	`bool`	`True`	Check which files Cognee already knows and whether they were cognified. When `False`, every `cognee_status` is `unknown`
`relationship_spec`	`dict` or `GraphSchemaSpec`	built-in spec	Custom relationship spec, written in the JSON graph-model DSL
`dataset_prefix`	`str`	`""`	Prefix for proposed dataset names
`max_sample_bytes`	`int`	`65536`	Bytes of each file sampled for content-based detection

Apply-phase keywords (remember(report), or alongside auto_apply=True). When omitted, the value stored on the report is used:

Option	Type	Default	What it does
`auto_apply`	`bool`	`False`	Apply the report immediately in the same `dry_run="presort"` call
`apply_groups`	`list[str]`	all groups	Ingest only these groups, matched by group name or dataset name. Raises `ValueError` when none of the names match a proposed group; names that miss alongside a name that matches are ignored
`skip_duplicates`	`bool`	`True`	Ingest one copy per duplicate cluster
`exclude_pii`	`bool`	`False`	Skip files with potential personal data
`node_set_extra`	`list[str]`	—	Extra node-set tags on top of `["presort", "<group name>"]`
`apply_graph`	`bool`	`False`	Also write the report’s relationship graph (files, groups, duplicates, PII tags) into its own dataset
`graph_dataset`	`str`	`<folder>_presort_graph`	Dataset for `apply_graph`

Without a configured LLM

Presort degrades instead of failing. The deterministic scan always runs; use_llm is downgraded to the deterministic pass; apply stages files with add() only, leaving cognify/improve for later; and apply_graph is skipped because writing the relationship graph needs embeddings. Each degradation is recorded as a warning on the report and logged.

Automatic presort

Set PRESORT_FOLDERS_ENABLED=true to presort plain folders automatically, with auto_apply on by default. The environment flag defaults to false, so ordinary remember(folder) calls are unchanged unless you opt in. Even when enabled, automatic presort applies only to a local directory path targeting main_dataset with no session_id, no dataset_id, and no content_type. Code-project directories keep the code-graph route, and remote (serve()) mode is excluded.

Restrictions

Presort scans the local filesystem, and is bounded to the permitted presort roots. Scanning a folder outside them raises

ValueError: Path is outside the allowed local file roots. Add the folder to COGNEE_ALLOWED_LOCAL_FILE_ROOTS (os.pathsep-separated list) to allow it, or use the CLI's --allow-root flag.

; reading a saved report from outside them raises the shorter ValueError: Local file path is outside allowed roots. ValueError is also raised for:

dry_run="presort" with session_id or any content_type
dry_run="presort" while connected to a remote instance via serve() — call cognee.disconnect() first
more than one folder path in a single presort call, or a file path instead of a folder
dry_run or session_id combined with applying a report

Additional keyword options

These power-user options are forwarded to the underlying ingestion and graph-building steps.

Option	Type	What it does
`graph_model`	`Any`	Overrides the graph schema/model used during graph building. Defaults to `KnowledgeGraph`; pass a `DataPoint` subclass to constrain extraction to your own fields and relationships. See Custom Graph Model.
`extractor`	`Literal["llm", "gliner_demo", "gliner"]`	Which implementation fills the extract-and-summarize step of the internal `cognify()` call. `"gliner_demo"` (alias `"gliner"`) builds the graph and the chunk summaries with the local GLiNER demo model instead of the LLM; omitting it falls back to the `GRAPH_EXTRACTOR` setting, which defaults to `"auto"` — the LLM path with a usable LLM key, the GLiNER demo without one. Rejected with `ValueError` when combined with `session_id` or while connected to a remote instance via `serve()` — both check only whether you passed the argument, so a `GRAPH_EXTRACTOR` setting is ignored rather than rejected on those paths. `dry_run=True` rejects the resolved extractor, so the setting raises there too. The combinations `cognify()` itself refuses — a custom `graph_model`, `temporal_cognify=True` — apply to `remember()` as well. See LLM-free extraction with GLiNER.
`node_set`	`List[str]`	Tags ingested content with one or more node sets.
`dataset_id`	`UUID`	Targets a specific existing dataset by UUID instead of resolving only by name.
`preferred_loaders`	`list`	Chooses preferred loaders for source files.
`importance_weight`	`float`	Stores a retrieval-ranking weight on ingested data records.
`incremental_loading`	`bool`	Reuses existing dataset state and processes only new or changed content when supported.
`data_per_batch`	`int`	Controls ingestion batching.
`chunks_per_batch`	`int`	Controls chunk-processing batching during graph building.
`config`	`Config`	Overrides the full Cognee config for the graph-building step.
`temporal_cognify`	`bool`	Enables temporal-aware graph building during the internal `cognify()` step.
`user`	`object`	Runs the operation under a specific user context.
`vector_db_config`	`dict`	Overrides vector database configuration for this call.
`graph_db_config`	`dict`	Overrides graph database configuration for this call.
`llm_config`	`LLMConfig`	LLM settings to install into the current async context and forward to both the ingestion and graph-building steps. Uses the active context config or global LLM config when omitted. Import from `cognee.infrastructure.llm.config`.
`embedding_config`	`EmbeddingConfig`	Embedding settings to install into the current async context and forward to both the ingestion and graph-building steps. Uses the active context config or global embedding config when omitted. Import from `cognee.infrastructure.databases.vector.embeddings.config`.

Return value

remember() returns:

RememberResult for normal ingestion runs. You can inspect fields like status, dataset_name, session_ids, elapsed_seconds, and raw_result, or await the result when background mode is enabled.
DryRunEstimate when dry_run=True, with aggregate token/cost totals plus the per-stage breakdown described above.
PresortReport when dry_run="presort", described under Folder presort.
dict of {dataset_name: RememberResult} when data is a presort report.

A blocking permanent-memory run whose graph build fails does not return a RememberResult with status="errored" — it raises CognifyFailedError, carrying the dataset name and the root cause (error_class, error_message). Pass raise_on_error=False to get the errored result object back instead:

import cognee
from cognee.modules.pipelines.exceptions import CognifyFailedError

try:
    result = await cognee.remember("Einstein was born in Ulm.")
except CognifyFailedError as error:
    print(error.error_class, error.error_message)

Background runs (run_in_background=True) still surface the failure on the result object rather than raising, since there is no caller left to catch the exception: await the result and read status == "errored" along with pipeline_run_id and raw_result. See Failed runs for the full behavior of the underlying cognify() step.

Examples

import cognee

# Permanent memory
result = await cognee.remember(
    "Cognee turns documents into AI memory.",
    dataset_name="docs",
)
print(result.status)

# Session memory
await cognee.remember(
    "The customer prefers weekly updates.",
    session_id="sales_chat_1",
)

See also add() and cognify() if you need direct control over the legacy pipeline steps.

​cognee.remember()

​Description

​Parameters

​Dry-run cost estimation

​Folder presort

​The report

​Applying a report

​Presort options

​Without a configured LLM

​Automatic presort

​Restrictions

​Additional keyword options

​Return value

​Examples

​Related

cognee.remember()

Description

Parameters

Dry-run cost estimation

Folder presort

The report

Applying a report

Presort options

Without a configured LLM

Automatic presort

Restrictions

Additional keyword options

Return value

Examples

Related