Metadata-Version: 2.4
Name: psg_recall
Version: 0.1.0
Summary: A library to help facilitate memory recall
Home-page: https://github.com/problemsolversguild/psg_recall
Author: Kevin Bird
Author-email: kevin@problemsolversguild.com
License: Apache Software License 2.0
Keywords: nbdev jupyter notebook python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
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: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: dialoghelper
Requires-Dist: sentence_transformers
Provides-Extra: dev
Requires-Dist: nbdev; extra == "dev"
Requires-Dist: ipykernel; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# psg_recall


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## Usage

### Installation

Install latest from the GitHub
[repository](https://github.com/problemsolversguild/psg_recall):

``` sh
$ pip install git+https://github.com/problemsolversguild/psg_recall.git
```

or from [pypi](https://pypi.org/project/psg_recall/)

``` sh
$ pip install psg_recall
```

### Documentation

Documentation can be found hosted on this GitHub
[repository](https://github.com/problemsolversguild/psg_recall)’s
[pages](https://problemsolversguild.github.io/psg_recall/). Additionally
you can find package manager specific guidelines on
[pypi](https://pypi.org/project/psg_recall/).

## How to use

`psg_recall` provides persistent memory storage at three levels:

- **Global** - Memories shared across all projects (stored in
  `~/.solveit_memory/`)
- **Project** - Memories for the current project directory (stored in
  `.memory/`)
- **File** - Memories tied to a specific file (stored in
  `.memory/{filename}_memory.txt`)

``` python
from psg_recall.storage import remember, recall, recall_all, recall_history, forget
```

### Storing memories

Use
[`remember()`](https://problemsolversguild.github.io/psg_recall/storage.html#remember)
to store a key-value pair. By default it stores at the project level:

``` python
# Store a project-level memory
remember("user_name", "Alice")
```

    'Remembered (project): user_name'

``` python
# Store a global memory (available across all projects)
remember("api_preference", "openai", level="global")
```

    'Remembered (global): api_preference'

``` python
# Store a file-specific memory (context specifies the filename)
remember("last_edit", "fixed bug on line 42", level="file", context="main.py")
```

    'Remembered (file): last_edit'

### Recalling memories

Use
[`recall()`](https://problemsolversguild.github.io/psg_recall/storage.html#recall)
to retrieve memories from a specific level. Returns `None` if the key
doesn’t exist:

``` python
# Recall a specific key from project level
recall(key="user_name")
```

    'Alice'

``` python
# Recall all project-level memories
recall()
```

    'user_name: Alice\nproject_goal: Build a chatbot for customer support\ntech_stack: The tools and programming languages being used are Python with FastAPI'

``` python
# Recall from global level
recall(level="global")
```

    'api_preference: openai'

### Recalling from all levels

Use
[`recall_all()`](https://problemsolversguild.github.io/psg_recall/storage.html#recall_all)
to get memories from global, project, and file levels combined:

``` python
# Get all memories across all levels
print(recall_all(context="main.py"))  # include file context to also get file-level memories
```

    === GLOBAL ===
    api_preference: openai
    === PROJECT ===
    user_name: Alice
    project_goal: Build a chatbot for customer support
    tech_stack: The tools and programming languages being used are Python with FastAPI
    === FILE ===
    last_edit: fixed bug on line 42

### Forgetting memories

Use
[`forget()`](https://problemsolversguild.github.io/psg_recall/storage.html#forget)
to remove a key from memory. This also records the removal in history:

``` python
# Forget a project-level memory
forget("user_name")
```

    'Forgot (project): user_name'

### Viewing history

Use
[`recall_history()`](https://problemsolversguild.github.io/psg_recall/storage.html#recall_history)
to see past changes to memories, including timestamps and whether values
were remembered or forgotten:

``` python
# View all history for project level
print(recall_history())
```

    2026-01-05 04:33:41 | remember | user_name | Alice
    2026-01-05 04:33:41 | forget | user_name | Alice
    2026-01-05 04:33:57 | remember | user_name | Alice
    2026-01-05 04:33:57 | forget | user_name | Alice
    2026-01-13 04:37:33 | user_name | remember | Alice
    2026-01-13 04:41:06 | user_name | remember | Alice
    2026-01-13 04:41:21 | user_name | remember | Alice
    2026-01-13 04:41:21 | user_name | forget | Alice

``` python
# View history for a specific key
print(recall_history(key="user_name"))
```

    2026-01-05 04:33:41 | remember | user_name | Alice
    2026-01-05 04:33:41 | forget | user_name | Alice
    2026-01-05 04:33:57 | remember | user_name | Alice
    2026-01-05 04:33:57 | forget | user_name | Alice
    2026-01-13 04:37:33 | user_name | remember | Alice
    2026-01-13 04:41:06 | user_name | remember | Alice
    2026-01-13 04:41:21 | user_name | remember | Alice
    2026-01-13 04:41:21 | user_name | forget | Alice

### Memory Index

The memory index automatically catalogs all memory files in your
project, making it easy for you (or AI agents) to quickly understand
what information is available and where to find it.

**The index is completely automatic** - it’s created and updated in the
background every time you
[`remember()`](https://problemsolversguild.github.io/psg_recall/storage.html#remember)
or
[`forget()`](https://problemsolversguild.github.io/psg_recall/storage.html#forget)
something. You never need to manually create or update it.

``` python
from psg_recall.storage import get_index

# Get the current index (auto-creates if needed)
index = get_index()

# Display what's available
print("Available Memory Files:")
for filename, info in index['files'].items():
    print(f"\n  {filename} ({info['type']} level)")
    print(f"    {info['summary']}")
    print(f"    Keys: {', '.join(info['sample_keys'][:3])}")
```

The index is stored in `.memory/index.json` and contains: - **Summary**
of what each memory file contains - **Number of keys** in each file -
**Sample keys** for quick reference - **Topics** extracted from key
names - **File type** (global, project, or file-level) - **Last
modified** timestamp

#### Disabling Auto-Index (Optional)

If you need to disable automatic indexing for performance-critical
scenarios:

``` python
import os
os.environ['RECALL_DISABLE_INDEX'] = 'true'
```

#### Manual Rebuild

If you ever need to manually rebuild the index (e.g., for repair):

``` python
from psg_recall.storage import rebuild_index
rebuild_index()
```

## Export

``` python
from nbdev import nbdev_export
from nbdev.quarto import nbdev_docs

nbdev_export()
nbdev_docs()
```

    pandoc -o README.md
      to: >-
        commonmark+autolink_bare_uris+emoji+footnotes+gfm_auto_identifiers+pipe_tables+strikeout+task_lists+tex_math_dollars
      output-file: index.html
      standalone: true
      default-image-extension: png
      variables: {}
      
    metadata
      description: A library to help facilitate memory recall
      title: psg_recall
      
    Output created: _docs/README.md

    [1/3] 00_recall.ipynb
    [2/3] 01_storage.ipynb
    [3/3] index.ipynb

    Output created: _docs/index.html
