psg-recall 0.1.0

A library to help facilitate memory recall

psg_recall

Usage

Installation

Install latest from the GitHub repository:

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

or from pypi

$ pip install psg_recall

Documentation

Documentation can be found hosted on this GitHub repository’s pages. Additionally you can find package manager specific guidelines on pypi.

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)

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

Storing memories

Use remember() to store a key-value pair. By default it stores at the project level:

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

'Remembered (project): user_name'

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

'Remembered (global): api_preference'

# 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() to retrieve memories from a specific level. Returns None if the key doesn’t exist:

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

'Alice'

# 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'

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

'api_preference: openai'

Recalling from all levels

Use recall_all() to get memories from global, project, and file levels combined:

# 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() to remove a key from memory. This also records the removal in history:

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

'Forgot (project): user_name'

Viewing history

Use recall_history() to see past changes to memories, including timestamps and whether values were remembered or forgotten:

# 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

# 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() or forget() something. You never need to manually create or update it.

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:

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

Manual Rebuild

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

from psg_recall.storage import rebuild_index
rebuild_index()

Export

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